From 9e427cbd5779dcfdfa7995ea29858814c83dee34 Mon Sep 17 00:00:00 2001 From: Mladen Jablanovic Date: Mon, 19 Oct 2026 15:03:31 +0200 Subject: [PATCH 1/4] docs(API): document key and locale query qualifiers for translations #STRINGS-3829 The `q` parameter of translations index/search and the batch actions supports `key.id`, `key.name`, `locale.id` and `locale.name`, but only `id` (translation ids), `tags`, `unverified`, `excluded` and the date qualifiers were documented. The only documented way to act on the translations of specific keys was therefore to look up translation ids first. - Add the four qualifiers to the `q` descriptions (omitting the one that is redundant on the key and locale routes) - Clarify that `id:` takes translation ids - Add a `key.id` example to batch unverify Co-Authored-By: Claude Sonnet 5.5 --- doc/compiled.json | 22 +++++++++++----------- paths/translations/batch_exclude.yaml | 6 +++++- paths/translations/batch_include.yaml | 6 +++++- paths/translations/batch_review.yaml | 6 +++++- paths/translations/batch_unreview.yaml | 6 +++++- paths/translations/batch_unverify.yaml | 11 +++++++++-- paths/translations/batch_verify.yaml | 6 +++++- paths/translations/index.yaml | 6 +++++- paths/translations/index_keys.yaml | 4 +++- paths/translations/index_locale.yaml | 4 +++- paths/translations/search.yaml | 6 +++++- 11 files changed, 61 insertions(+), 22 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index bf255f734..adb8b0755 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -28258,7 +28258,7 @@ } }, { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n\n* `id:translation_id,...` for queries on a comma-separated list of ids\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n* `reviewed_after:2013-02-21T00:00:00Z` for fetching translations that were reviewed after the given timestamp\n\nFind more examples [here](/en/api/strings/usage-examples).\n", + "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n* `reviewed_after:2013-02-21T00:00:00Z` for fetching translations that were reviewed after the given timestamp\n\nFind more examples [here](/en/api/strings/usage-examples).\n", "example": "PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center", "name": "q", "in": "query", @@ -28512,7 +28512,7 @@ } }, { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n- `id:translation_id,...` for queries on a comma-separated list of ids\n- `unverified:{true|false}` for verification status\n- `tags:XYZ` for tags on the translation\n- `excluded:{true|false}` for exclusion status\n- `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", + "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n- `id:translation_id,...` for queries on a comma-separated list of translation ids\n- `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n- `key.name:key_name,...` for queries on a comma-separated list of translation key names\n- `unverified:{true|false}` for verification status\n- `tags:XYZ` for tags on the translation\n- `excluded:{true|false}` for exclusion status\n- `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", "example": "PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center", "name": "q", "in": "query", @@ -28634,7 +28634,7 @@ } }, { - "description": "Specify a query to find translations by content (including wildcards).\n\nThe following qualifiers are supported in the query:\n\n* `id:translation_id,...` for queries on a comma-separated list of ids\n* `unverified:{true|false}` for verification status\n* `tags:XYZ` for tags on the translation\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", + "description": "Specify a query to find translations by content (including wildcards).\n\nThe following qualifiers are supported in the query:\n\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `unverified:{true|false}` for verification status\n* `tags:XYZ` for tags on the translation\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", "example": "PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center", "name": "q", "in": "query", @@ -28805,7 +28805,7 @@ "example": "desc" }, "q": { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n\n- `id:translation_id,...` for queries on a comma-separated list of ids\n- `tags:XYZ` for tags on the translation\n- `unverified:{true|false}` for verification status\n- `excluded:{true|false}` for exclusion status\n- `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", + "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n\n- `id:translation_id,...` for queries on a comma-separated list of translation ids\n- `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n- `key.name:key_name,...` for queries on a comma-separated list of translation key names\n- `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n- `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n- `tags:XYZ` for tags on the translation\n- `unverified:{true|false}` for verification status\n- `excluded:{true|false}` for exclusion status\n- `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", "type": "string", "example": "PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center" } @@ -29661,7 +29661,7 @@ "example": "fc2f11dd6a658fa9652f6f0a9ebee688" }, "q": { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n* `id:translation_id,...` for queries on a comma-separated list of ids\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", + "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", "type": "string", "example": "PhraseApp*%20unverified:true%20tags:feature,center" } @@ -29676,7 +29676,7 @@ "/projects/{project_id}/translations/unverify": { "patch": { "summary": "Unverify translations by query", - "description": "Mark translations matching query as unverified.", + "description": "Mark translations matching query as unverified.\n\nTo unverify the translations of specific keys, filter by key id (and optionally locale) directly, for example `key.id:KEY_ID_1,KEY_ID_2 locale.id:LOCALE_ID`. There is no need to look up translation ids first.\n", "operationId": "translations/unverify-collection", "tags": [ "Translations" @@ -29755,7 +29755,7 @@ "example": "my-feature-branch" }, "q": { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n* `id:translation_id,...` for queries on a comma-separated list of ids\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", + "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", "type": "string", "example": "PhraseApp*%20verified:true%20tags:feature,center" }, @@ -29859,7 +29859,7 @@ "example": "my-feature-branch" }, "q": { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n\n* `id:translation_id,...` for queries on a comma-separated list of ids\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", + "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", "type": "string", "example": "PhraseApp*%reviewed:false%20tags:feature,center" } @@ -29953,7 +29953,7 @@ "example": "my-feature-branch" }, "q": { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n* `id:translation_id,...` for queries on a comma-separated list of ids\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", + "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", "type": "string", "example": "PhraseApp*%reviewed:true%20tags:feature,center" } @@ -30044,7 +30044,7 @@ "example": "my-feature-branch" }, "q": { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n\n* `id:translation_id,...` for queries on a comma-separated list of ids\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", + "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", "type": "string", "example": "PhraseApp*%20verified:true%20tags:feature,center" }, @@ -30145,7 +30145,7 @@ "example": "my-feature-branch" }, "q": { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n- `id:translation_id,...` for queries on a comma-separated list of ids\n- `tags:XYZ` for tags on the translation\n- `unverified:{true|false}` for verification status\n- `excluded:{true|false}` for exclusion status\n- `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", + "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n- `id:translation_id,...` for queries on a comma-separated list of translation ids\n- `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n- `key.name:key_name,...` for queries on a comma-separated list of translation key names\n- `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n- `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n- `tags:XYZ` for tags on the translation\n- `unverified:{true|false}` for verification status\n- `excluded:{true|false}` for exclusion status\n- `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", "type": "string", "example": "PhraseApp*%20verified:true%20tags:feature,center" }, diff --git a/paths/translations/batch_exclude.yaml b/paths/translations/batch_exclude.yaml index 6623c35a4..e300e2f58 100644 --- a/paths/translations/batch_exclude.yaml +++ b/paths/translations/batch_exclude.yaml @@ -66,7 +66,11 @@ requestBody: The following qualifiers are supported in the query: - * `id:translation_id,...` for queries on a comma-separated list of ids + * `id:translation_id,...` for queries on a comma-separated list of translation ids + * `key.id:key_id,...` for queries on a comma-separated list of translation key ids + * `key.name:key_name,...` for queries on a comma-separated list of translation key names + * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids + * `locale.name:locale_name,...` for queries on a comma-separated list of locale names * `tags:XYZ` for tags on the translation * `unverified:{true|false}` for verification status * `excluded:{true|false}` for exclusion status diff --git a/paths/translations/batch_include.yaml b/paths/translations/batch_include.yaml index 1d83f0249..172a69698 100644 --- a/paths/translations/batch_include.yaml +++ b/paths/translations/batch_include.yaml @@ -65,7 +65,11 @@ requestBody: *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* The following qualifiers are supported in the query: - - `id:translation_id,...` for queries on a comma-separated list of ids + - `id:translation_id,...` for queries on a comma-separated list of translation ids + - `key.id:key_id,...` for queries on a comma-separated list of translation key ids + - `key.name:key_name,...` for queries on a comma-separated list of translation key names + - `locale.id:locale_id,...` for queries on a comma-separated list of locale ids + - `locale.name:locale_name,...` for queries on a comma-separated list of locale names - `tags:XYZ` for tags on the translation - `unverified:{true|false}` for verification status - `excluded:{true|false}` for exclusion status diff --git a/paths/translations/batch_review.yaml b/paths/translations/batch_review.yaml index 39d9a8a19..93b8b37cb 100644 --- a/paths/translations/batch_review.yaml +++ b/paths/translations/batch_review.yaml @@ -68,7 +68,11 @@ requestBody: The following qualifiers are supported in the query: - * `id:translation_id,...` for queries on a comma-separated list of ids + * `id:translation_id,...` for queries on a comma-separated list of translation ids + * `key.id:key_id,...` for queries on a comma-separated list of translation key ids + * `key.name:key_name,...` for queries on a comma-separated list of translation key names + * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids + * `locale.name:locale_name,...` for queries on a comma-separated list of locale names * `tags:XYZ` for tags on the translation * `unverified:{true|false}` for verification status * `excluded:{true|false}` for exclusion status diff --git a/paths/translations/batch_unreview.yaml b/paths/translations/batch_unreview.yaml index 62558d80a..55d3c3cc9 100644 --- a/paths/translations/batch_unreview.yaml +++ b/paths/translations/batch_unreview.yaml @@ -66,7 +66,11 @@ requestBody: *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* The following qualifiers are supported in the query: - * `id:translation_id,...` for queries on a comma-separated list of ids + * `id:translation_id,...` for queries on a comma-separated list of translation ids + * `key.id:key_id,...` for queries on a comma-separated list of translation key ids + * `key.name:key_name,...` for queries on a comma-separated list of translation key names + * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids + * `locale.name:locale_name,...` for queries on a comma-separated list of locale names * `tags:XYZ` for tags on the translation * `unverified:{true|false}` for verification status * `excluded:{true|false}` for exclusion status diff --git a/paths/translations/batch_unverify.yaml b/paths/translations/batch_unverify.yaml index c33a527b2..9932eb55b 100644 --- a/paths/translations/batch_unverify.yaml +++ b/paths/translations/batch_unverify.yaml @@ -1,6 +1,9 @@ --- summary: Unverify translations by query -description: Mark translations matching query as unverified. +description: | + Mark translations matching query as unverified. + + To unverify the translations of specific keys, filter by key id (and optionally locale) directly, for example `key.id:KEY_ID_1,KEY_ID_2 locale.id:LOCALE_ID`. There is no need to look up translation ids first. operationId: translations/unverify-collection tags: - Translations @@ -67,7 +70,11 @@ requestBody: *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* The following qualifiers are supported in the query: - * `id:translation_id,...` for queries on a comma-separated list of ids + * `id:translation_id,...` for queries on a comma-separated list of translation ids + * `key.id:key_id,...` for queries on a comma-separated list of translation key ids + * `key.name:key_name,...` for queries on a comma-separated list of translation key names + * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids + * `locale.name:locale_name,...` for queries on a comma-separated list of locale names * `tags:XYZ` for tags on the translation * `unverified:{true|false}` for verification status * `excluded:{true|false}` for exclusion status diff --git a/paths/translations/batch_verify.yaml b/paths/translations/batch_verify.yaml index 8fc68d363..ad50086ea 100644 --- a/paths/translations/batch_verify.yaml +++ b/paths/translations/batch_verify.yaml @@ -71,7 +71,11 @@ requestBody: *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* The following qualifiers are supported in the query: - * `id:translation_id,...` for queries on a comma-separated list of ids + * `id:translation_id,...` for queries on a comma-separated list of translation ids + * `key.id:key_id,...` for queries on a comma-separated list of translation key ids + * `key.name:key_name,...` for queries on a comma-separated list of translation key names + * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids + * `locale.name:locale_name,...` for queries on a comma-separated list of locale names * `tags:XYZ` for tags on the translation * `unverified:{true|false}` for verification status * `excluded:{true|false}` for exclusion status diff --git a/paths/translations/index.yaml b/paths/translations/index.yaml index e3eccfc6c..c565f5fb4 100644 --- a/paths/translations/index.yaml +++ b/paths/translations/index.yaml @@ -51,7 +51,11 @@ parameters: The following qualifiers are supported in the query: - * `id:translation_id,...` for queries on a comma-separated list of ids + * `id:translation_id,...` for queries on a comma-separated list of translation ids + * `key.id:key_id,...` for queries on a comma-separated list of translation key ids + * `key.name:key_name,...` for queries on a comma-separated list of translation key names + * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids + * `locale.name:locale_name,...` for queries on a comma-separated list of locale names * `tags:XYZ` for tags on the translation * `unverified:{true|false}` for verification status * `excluded:{true|false}` for exclusion status diff --git a/paths/translations/index_keys.yaml b/paths/translations/index_keys.yaml index 1828c2467..0a876776e 100644 --- a/paths/translations/index_keys.yaml +++ b/paths/translations/index_keys.yaml @@ -33,7 +33,9 @@ parameters: The following qualifiers are supported in the query: - * `id:translation_id,...` for queries on a comma-separated list of ids + * `id:translation_id,...` for queries on a comma-separated list of translation ids + * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids + * `locale.name:locale_name,...` for queries on a comma-separated list of locale names * `unverified:{true|false}` for verification status * `tags:XYZ` for tags on the translation * `excluded:{true|false}` for exclusion status diff --git a/paths/translations/index_locale.yaml b/paths/translations/index_locale.yaml index dbc7d821e..6d61a877a 100644 --- a/paths/translations/index_locale.yaml +++ b/paths/translations/index_locale.yaml @@ -35,7 +35,9 @@ parameters: *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* The following qualifiers are supported in the query: - - `id:translation_id,...` for queries on a comma-separated list of ids + - `id:translation_id,...` for queries on a comma-separated list of translation ids + - `key.id:key_id,...` for queries on a comma-separated list of translation key ids + - `key.name:key_name,...` for queries on a comma-separated list of translation key names - `unverified:{true|false}` for verification status - `tags:XYZ` for tags on the translation - `excluded:{true|false}` for exclusion status diff --git a/paths/translations/search.yaml b/paths/translations/search.yaml index 3a589237d..49916df6c 100644 --- a/paths/translations/search.yaml +++ b/paths/translations/search.yaml @@ -80,7 +80,11 @@ requestBody: The following qualifiers are supported in the query: - - `id:translation_id,...` for queries on a comma-separated list of ids + - `id:translation_id,...` for queries on a comma-separated list of translation ids + - `key.id:key_id,...` for queries on a comma-separated list of translation key ids + - `key.name:key_name,...` for queries on a comma-separated list of translation key names + - `locale.id:locale_id,...` for queries on a comma-separated list of locale ids + - `locale.name:locale_name,...` for queries on a comma-separated list of locale names - `tags:XYZ` for tags on the translation - `unverified:{true|false}` for verification status - `excluded:{true|false}` for exclusion status From d5e9f1bc2eb02f411a4ba97d6d6a06e273e45b91 Mon Sep 17 00:00:00 2001 From: Mladen Jablanovic Date: Mon, 19 Oct 2026 15:06:32 +0200 Subject: [PATCH 2/4] docs(API): share translation query description via references #STRINGS-3829 Define the `q` description once as the `translations_q` query parameter (translations index on the project, locale and key routes) and once as the `translation_query` schema (request body of translations search and the batch actions) instead of repeating it in ten path files. All qualifiers work on every translations route, so the per-route omissions are dropped, and the examples now use valid qualifiers. Co-Authored-By: Claude Sonnet 5.5 --- doc/compiled.json | 66 ++++++++++---------------- parameters.yaml | 24 ++++++++++ paths/translations/batch_exclude.yaml | 21 +------- paths/translations/batch_include.yaml | 20 +------- paths/translations/batch_review.yaml | 21 +------- paths/translations/batch_unreview.yaml | 20 +------- paths/translations/batch_unverify.yaml | 20 +------- paths/translations/batch_verify.yaml | 20 +------- paths/translations/index.yaml | 25 +--------- paths/translations/index_keys.yaml | 20 +------- paths/translations/index_locale.yaml | 21 +------- paths/translations/search.yaml | 21 +------- schemas.yaml | 2 + schemas/translation_query.yaml | 22 +++++++++ 14 files changed, 82 insertions(+), 241 deletions(-) create mode 100644 schemas/translation_query.yaml diff --git a/doc/compiled.json b/doc/compiled.json index adb8b0755..ddebf16f4 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -3121,6 +3121,11 @@ } } }, + "translation_query": { + "type": "string", + "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n* `reviewed_after:2013-02-21T00:00:00Z` for fetching translations that were reviewed after the given timestamp\n\nFind more examples [here](/en/api/strings/usage-examples).\n", + "example": "PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center" + }, "translation_version": { "type": "object", "title": "translation_version", @@ -5821,6 +5826,15 @@ "type": "string" } }, + "translations_q": { + "in": "query", + "name": "q", + "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n* `reviewed_after:2013-02-21T00:00:00Z` for fetching translations that were reviewed after the given timestamp\n\nFind more examples [here](/en/api/strings/usage-examples).\n", + "example": "PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center", + "schema": { + "type": "string" + } + }, "job_owner": { "description": "filter by user owning job", "example": "abcd1234cdef1234abcd1234cdef1234", @@ -28258,13 +28272,7 @@ } }, { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n* `reviewed_after:2013-02-21T00:00:00Z` for fetching translations that were reviewed after the given timestamp\n\nFind more examples [here](/en/api/strings/usage-examples).\n", - "example": "PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center", - "name": "q", - "in": "query", - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/translations_q" } ], "responses": { @@ -28512,13 +28520,7 @@ } }, { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n- `id:translation_id,...` for queries on a comma-separated list of translation ids\n- `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n- `key.name:key_name,...` for queries on a comma-separated list of translation key names\n- `unverified:{true|false}` for verification status\n- `tags:XYZ` for tags on the translation\n- `excluded:{true|false}` for exclusion status\n- `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", - "example": "PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center", - "name": "q", - "in": "query", - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/translations_q" } ], "responses": { @@ -28634,13 +28636,7 @@ } }, { - "description": "Specify a query to find translations by content (including wildcards).\n\nThe following qualifiers are supported in the query:\n\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `unverified:{true|false}` for verification status\n* `tags:XYZ` for tags on the translation\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", - "example": "PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center", - "name": "q", - "in": "query", - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/translations_q" } ], "responses": { @@ -28805,9 +28801,7 @@ "example": "desc" }, "q": { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n\n- `id:translation_id,...` for queries on a comma-separated list of translation ids\n- `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n- `key.name:key_name,...` for queries on a comma-separated list of translation key names\n- `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n- `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n- `tags:XYZ` for tags on the translation\n- `unverified:{true|false}` for verification status\n- `excluded:{true|false}` for exclusion status\n- `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", - "type": "string", - "example": "PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center" + "$ref": "#/components/schemas/translation_query" } } } @@ -29661,9 +29655,7 @@ "example": "fc2f11dd6a658fa9652f6f0a9ebee688" }, "q": { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", - "type": "string", - "example": "PhraseApp*%20unverified:true%20tags:feature,center" + "$ref": "#/components/schemas/translation_query" } } } @@ -29755,9 +29747,7 @@ "example": "my-feature-branch" }, "q": { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", - "type": "string", - "example": "PhraseApp*%20verified:true%20tags:feature,center" + "$ref": "#/components/schemas/translation_query" }, "sort": { "description": "Sort criteria. Can be one of: key_name, created_at, updated_at.", @@ -29859,9 +29849,7 @@ "example": "my-feature-branch" }, "q": { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", - "type": "string", - "example": "PhraseApp*%reviewed:false%20tags:feature,center" + "$ref": "#/components/schemas/translation_query" } } } @@ -29953,9 +29941,7 @@ "example": "my-feature-branch" }, "q": { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", - "type": "string", - "example": "PhraseApp*%reviewed:true%20tags:feature,center" + "$ref": "#/components/schemas/translation_query" } } } @@ -30044,9 +30030,7 @@ "example": "my-feature-branch" }, "q": { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", - "type": "string", - "example": "PhraseApp*%20verified:true%20tags:feature,center" + "$ref": "#/components/schemas/translation_query" }, "sort": { "description": "Sort criteria. Can be one of: key_name, created_at, updated_at.", @@ -30145,9 +30129,7 @@ "example": "my-feature-branch" }, "q": { - "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n- `id:translation_id,...` for queries on a comma-separated list of translation ids\n- `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n- `key.name:key_name,...` for queries on a comma-separated list of translation key names\n- `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n- `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n- `tags:XYZ` for tags on the translation\n- `unverified:{true|false}` for verification status\n- `excluded:{true|false}` for exclusion status\n- `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n\nFind more examples [here](/en/api/strings/usage-examples).\n", - "type": "string", - "example": "PhraseApp*%20verified:true%20tags:feature,center" + "$ref": "#/components/schemas/translation_query" }, "sort": { "description": "Sort criteria. Can be one of: key_name, created_at, updated_at.", diff --git a/parameters.yaml b/parameters.yaml index 048cd2972..06436c1a4 100644 --- a/parameters.yaml +++ b/parameters.yaml @@ -286,6 +286,30 @@ q: in: query schema: type: string +translations_q: + in: query + name: q + description: | + Specify a query to find translations by content (including wildcards). + + *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* + + The following qualifiers are supported in the query: + * `id:translation_id,...` for queries on a comma-separated list of translation ids + * `key.id:key_id,...` for queries on a comma-separated list of translation key ids + * `key.name:key_name,...` for queries on a comma-separated list of translation key names + * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids + * `locale.name:locale_name,...` for queries on a comma-separated list of locale names + * `tags:XYZ` for tags on the translation + * `unverified:{true|false}` for verification status + * `excluded:{true|false}` for exclusion status + * `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries + * `reviewed_after:2013-02-21T00:00:00Z` for fetching translations that were reviewed after the given timestamp + + Find more examples [here](/en/api/strings/usage-examples). + example: PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center + schema: + type: string job_owner: description: filter by user owning job example: abcd1234cdef1234abcd1234cdef1234 diff --git a/paths/translations/batch_exclude.yaml b/paths/translations/batch_exclude.yaml index e300e2f58..63a1464a6 100644 --- a/paths/translations/batch_exclude.yaml +++ b/paths/translations/batch_exclude.yaml @@ -59,26 +59,7 @@ requestBody: type: string example: my-feature-branch q: - description: | - Specify a query to find translations by content (including wildcards). - - *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* - - The following qualifiers are supported in the query: - - * `id:translation_id,...` for queries on a comma-separated list of translation ids - * `key.id:key_id,...` for queries on a comma-separated list of translation key ids - * `key.name:key_name,...` for queries on a comma-separated list of translation key names - * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids - * `locale.name:locale_name,...` for queries on a comma-separated list of locale names - * `tags:XYZ` for tags on the translation - * `unverified:{true|false}` for verification status - * `excluded:{true|false}` for exclusion status - * `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries - - Find more examples [here](/en/api/strings/usage-examples). - type: string - example: PhraseApp*%20verified:true%20tags:feature,center + "$ref": "../../schemas/translation_query.yaml#/translation_query" sort: description: 'Sort criteria. Can be one of: key_name, created_at, updated_at.' type: string diff --git a/paths/translations/batch_include.yaml b/paths/translations/batch_include.yaml index 172a69698..41debfe64 100644 --- a/paths/translations/batch_include.yaml +++ b/paths/translations/batch_include.yaml @@ -59,25 +59,7 @@ requestBody: type: string example: my-feature-branch q: - description: | - Specify a query to find translations by content (including wildcards). - - *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* - - The following qualifiers are supported in the query: - - `id:translation_id,...` for queries on a comma-separated list of translation ids - - `key.id:key_id,...` for queries on a comma-separated list of translation key ids - - `key.name:key_name,...` for queries on a comma-separated list of translation key names - - `locale.id:locale_id,...` for queries on a comma-separated list of locale ids - - `locale.name:locale_name,...` for queries on a comma-separated list of locale names - - `tags:XYZ` for tags on the translation - - `unverified:{true|false}` for verification status - - `excluded:{true|false}` for exclusion status - - `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries - - Find more examples [here](/en/api/strings/usage-examples). - type: string - example: PhraseApp*%20verified:true%20tags:feature,center + "$ref": "../../schemas/translation_query.yaml#/translation_query" sort: description: 'Sort criteria. Can be one of: key_name, created_at, updated_at.' type: string diff --git a/paths/translations/batch_review.yaml b/paths/translations/batch_review.yaml index 93b8b37cb..cc0cac965 100644 --- a/paths/translations/batch_review.yaml +++ b/paths/translations/batch_review.yaml @@ -61,24 +61,5 @@ requestBody: type: string example: my-feature-branch q: - description: | - Specify a query to find translations by content (including wildcards). - - *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* - - The following qualifiers are supported in the query: - - * `id:translation_id,...` for queries on a comma-separated list of translation ids - * `key.id:key_id,...` for queries on a comma-separated list of translation key ids - * `key.name:key_name,...` for queries on a comma-separated list of translation key names - * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids - * `locale.name:locale_name,...` for queries on a comma-separated list of locale names - * `tags:XYZ` for tags on the translation - * `unverified:{true|false}` for verification status - * `excluded:{true|false}` for exclusion status - * `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries - - Find more examples [here](/en/api/strings/usage-examples). - type: string - example: PhraseApp*%reviewed:false%20tags:feature,center + "$ref": "../../schemas/translation_query.yaml#/translation_query" x-cli-version: '2.5' diff --git a/paths/translations/batch_unreview.yaml b/paths/translations/batch_unreview.yaml index 55d3c3cc9..24297c3db 100644 --- a/paths/translations/batch_unreview.yaml +++ b/paths/translations/batch_unreview.yaml @@ -60,23 +60,5 @@ requestBody: type: string example: my-feature-branch q: - description: | - Specify a query to find translations by content (including wildcards). - - *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* - - The following qualifiers are supported in the query: - * `id:translation_id,...` for queries on a comma-separated list of translation ids - * `key.id:key_id,...` for queries on a comma-separated list of translation key ids - * `key.name:key_name,...` for queries on a comma-separated list of translation key names - * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids - * `locale.name:locale_name,...` for queries on a comma-separated list of locale names - * `tags:XYZ` for tags on the translation - * `unverified:{true|false}` for verification status - * `excluded:{true|false}` for exclusion status - * `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries - - Find more examples [here](/en/api/strings/usage-examples). - type: string - example: PhraseApp*%reviewed:true%20tags:feature,center + "$ref": "../../schemas/translation_query.yaml#/translation_query" x-cli-version: '2.41' diff --git a/paths/translations/batch_unverify.yaml b/paths/translations/batch_unverify.yaml index 9932eb55b..5eca131f5 100644 --- a/paths/translations/batch_unverify.yaml +++ b/paths/translations/batch_unverify.yaml @@ -64,25 +64,7 @@ requestBody: type: string example: my-feature-branch q: - description: | - Specify a query to find translations by content (including wildcards). - - *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* - - The following qualifiers are supported in the query: - * `id:translation_id,...` for queries on a comma-separated list of translation ids - * `key.id:key_id,...` for queries on a comma-separated list of translation key ids - * `key.name:key_name,...` for queries on a comma-separated list of translation key names - * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids - * `locale.name:locale_name,...` for queries on a comma-separated list of locale names - * `tags:XYZ` for tags on the translation - * `unverified:{true|false}` for verification status - * `excluded:{true|false}` for exclusion status - * `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries - - Find more examples [here](/en/api/strings/usage-examples). - type: string - example: PhraseApp*%20verified:true%20tags:feature,center + "$ref": "../../schemas/translation_query.yaml#/translation_query" sort: description: 'Sort criteria. Can be one of: key_name, created_at, updated_at.' type: string diff --git a/paths/translations/batch_verify.yaml b/paths/translations/batch_verify.yaml index ad50086ea..bc624c8ef 100644 --- a/paths/translations/batch_verify.yaml +++ b/paths/translations/batch_verify.yaml @@ -65,23 +65,5 @@ requestBody: type: string example: fc2f11dd6a658fa9652f6f0a9ebee688 q: - description: | - Specify a query to find translations by content (including wildcards). - - *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* - - The following qualifiers are supported in the query: - * `id:translation_id,...` for queries on a comma-separated list of translation ids - * `key.id:key_id,...` for queries on a comma-separated list of translation key ids - * `key.name:key_name,...` for queries on a comma-separated list of translation key names - * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids - * `locale.name:locale_name,...` for queries on a comma-separated list of locale names - * `tags:XYZ` for tags on the translation - * `unverified:{true|false}` for verification status - * `excluded:{true|false}` for exclusion status - * `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries - - Find more examples [here](/en/api/strings/usage-examples). - type: string - example: PhraseApp*%20unverified:true%20tags:feature,center + "$ref": "../../schemas/translation_query.yaml#/translation_query" x-cli-version: '2.5' diff --git a/paths/translations/index.yaml b/paths/translations/index.yaml index c565f5fb4..34d84f60c 100644 --- a/paths/translations/index.yaml +++ b/paths/translations/index.yaml @@ -44,30 +44,7 @@ parameters: in: query schema: type: string -- description: | - Specify a query to find translations by content (including wildcards). - - *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* - - The following qualifiers are supported in the query: - - * `id:translation_id,...` for queries on a comma-separated list of translation ids - * `key.id:key_id,...` for queries on a comma-separated list of translation key ids - * `key.name:key_name,...` for queries on a comma-separated list of translation key names - * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids - * `locale.name:locale_name,...` for queries on a comma-separated list of locale names - * `tags:XYZ` for tags on the translation - * `unverified:{true|false}` for verification status - * `excluded:{true|false}` for exclusion status - * `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries - * `reviewed_after:2013-02-21T00:00:00Z` for fetching translations that were reviewed after the given timestamp - - Find more examples [here](/en/api/strings/usage-examples). - example: PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center - name: q - in: query - schema: - type: string +- "$ref": "../../parameters.yaml#/translations_q" responses: '200': description: OK diff --git a/paths/translations/index_keys.yaml b/paths/translations/index_keys.yaml index 0a876776e..04ae5c9d3 100644 --- a/paths/translations/index_keys.yaml +++ b/paths/translations/index_keys.yaml @@ -28,25 +28,7 @@ parameters: in: query schema: type: string -- description: | - Specify a query to find translations by content (including wildcards). - - The following qualifiers are supported in the query: - - * `id:translation_id,...` for queries on a comma-separated list of translation ids - * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids - * `locale.name:locale_name,...` for queries on a comma-separated list of locale names - * `unverified:{true|false}` for verification status - * `tags:XYZ` for tags on the translation - * `excluded:{true|false}` for exclusion status - * `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries - - Find more examples [here](/en/api/strings/usage-examples). - example: PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center - name: q - in: query - schema: - type: string +- "$ref": "../../parameters.yaml#/translations_q" responses: '200': description: OK diff --git a/paths/translations/index_locale.yaml b/paths/translations/index_locale.yaml index 6d61a877a..7c9526a1c 100644 --- a/paths/translations/index_locale.yaml +++ b/paths/translations/index_locale.yaml @@ -29,26 +29,7 @@ parameters: in: query schema: type: string -- description: | - Specify a query to find translations by content (including wildcards). - - *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* - - The following qualifiers are supported in the query: - - `id:translation_id,...` for queries on a comma-separated list of translation ids - - `key.id:key_id,...` for queries on a comma-separated list of translation key ids - - `key.name:key_name,...` for queries on a comma-separated list of translation key names - - `unverified:{true|false}` for verification status - - `tags:XYZ` for tags on the translation - - `excluded:{true|false}` for exclusion status - - `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries - - Find more examples [here](/en/api/strings/usage-examples). - example: PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center - name: q - in: query - schema: - type: string +- "$ref": "../../parameters.yaml#/translations_q" responses: '200': description: OK diff --git a/paths/translations/search.yaml b/paths/translations/search.yaml index 49916df6c..8ff46801d 100644 --- a/paths/translations/search.yaml +++ b/paths/translations/search.yaml @@ -73,24 +73,5 @@ requestBody: type: string example: desc q: - description: | - Specify a query to find translations by content (including wildcards). - - *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* - - The following qualifiers are supported in the query: - - - `id:translation_id,...` for queries on a comma-separated list of translation ids - - `key.id:key_id,...` for queries on a comma-separated list of translation key ids - - `key.name:key_name,...` for queries on a comma-separated list of translation key names - - `locale.id:locale_id,...` for queries on a comma-separated list of locale ids - - `locale.name:locale_name,...` for queries on a comma-separated list of locale names - - `tags:XYZ` for tags on the translation - - `unverified:{true|false}` for verification status - - `excluded:{true|false}` for exclusion status - - `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries - - Find more examples [here](/en/api/strings/usage-examples). - type: string - example: PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center + "$ref": "../../schemas/translation_query.yaml#/translation_query" x-cli-version: '2.5' diff --git a/schemas.yaml b/schemas.yaml index 10dd2a2bb..7765a2245 100644 --- a/schemas.yaml +++ b/schemas.yaml @@ -102,6 +102,8 @@ schemas: "$ref": schemas/translation_order.yaml#/translation_order pre_translation: "$ref": schemas/pre_translation.yaml#/pre_translation + translation_query: + "$ref": schemas/translation_query.yaml#/translation_query translation_version: "$ref": schemas/translation_version.yaml#/translation_version translation_version_with_user: diff --git a/schemas/translation_query.yaml b/schemas/translation_query.yaml new file mode 100644 index 000000000..cfda1b5c3 --- /dev/null +++ b/schemas/translation_query.yaml @@ -0,0 +1,22 @@ +--- +translation_query: + type: string + description: | + Specify a query to find translations by content (including wildcards). + + *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* + + The following qualifiers are supported in the query: + * `id:translation_id,...` for queries on a comma-separated list of translation ids + * `key.id:key_id,...` for queries on a comma-separated list of translation key ids + * `key.name:key_name,...` for queries on a comma-separated list of translation key names + * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids + * `locale.name:locale_name,...` for queries on a comma-separated list of locale names + * `tags:XYZ` for tags on the translation + * `unverified:{true|false}` for verification status + * `excluded:{true|false}` for exclusion status + * `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries + * `reviewed_after:2013-02-21T00:00:00Z` for fetching translations that were reviewed after the given timestamp + + Find more examples [here](/en/api/strings/usage-examples). + example: PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center From 69d8853d4d325769a144a7cbeb1b7f17f1bdb475 Mon Sep 17 00:00:00 2001 From: Mladen Jablanovic Date: Mon, 19 Oct 2026 15:09:37 +0200 Subject: [PATCH 3/4] docs(API): omit redundant query qualifiers on nested translations routes #STRINGS-3829 The locale route already fixes the locale and the key route already fixes the key, so `locale.*` and `key.*` respectively can only narrow the result to nothing. Document them only where they are meaningful, via `translations_locale_q` and `translations_key_q`. Co-Authored-By: Claude Sonnet 5.5 --- doc/compiled.json | 22 ++++++++++++-- parameters.yaml | 44 ++++++++++++++++++++++++++++ paths/translations/index_keys.yaml | 2 +- paths/translations/index_locale.yaml | 2 +- 4 files changed, 66 insertions(+), 4 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index ddebf16f4..66c2954ac 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -5835,6 +5835,24 @@ "type": "string" } }, + "translations_locale_q": { + "in": "query", + "name": "q", + "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n* `reviewed_after:2013-02-21T00:00:00Z` for fetching translations that were reviewed after the given timestamp\n\nFind more examples [here](/en/api/strings/usage-examples).\n", + "example": "PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center", + "schema": { + "type": "string" + } + }, + "translations_key_q": { + "in": "query", + "name": "q", + "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n* `reviewed_after:2013-02-21T00:00:00Z` for fetching translations that were reviewed after the given timestamp\n\nFind more examples [here](/en/api/strings/usage-examples).\n", + "example": "PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center", + "schema": { + "type": "string" + } + }, "job_owner": { "description": "filter by user owning job", "example": "abcd1234cdef1234abcd1234cdef1234", @@ -28520,7 +28538,7 @@ } }, { - "$ref": "#/components/parameters/translations_q" + "$ref": "#/components/parameters/translations_locale_q" } ], "responses": { @@ -28636,7 +28654,7 @@ } }, { - "$ref": "#/components/parameters/translations_q" + "$ref": "#/components/parameters/translations_key_q" } ], "responses": { diff --git a/parameters.yaml b/parameters.yaml index 06436c1a4..027224435 100644 --- a/parameters.yaml +++ b/parameters.yaml @@ -310,6 +310,50 @@ translations_q: example: PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center schema: type: string +translations_locale_q: + in: query + name: q + description: | + Specify a query to find translations by content (including wildcards). + + *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* + + The following qualifiers are supported in the query: + * `id:translation_id,...` for queries on a comma-separated list of translation ids + * `key.id:key_id,...` for queries on a comma-separated list of translation key ids + * `key.name:key_name,...` for queries on a comma-separated list of translation key names + * `tags:XYZ` for tags on the translation + * `unverified:{true|false}` for verification status + * `excluded:{true|false}` for exclusion status + * `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries + * `reviewed_after:2013-02-21T00:00:00Z` for fetching translations that were reviewed after the given timestamp + + Find more examples [here](/en/api/strings/usage-examples). + example: PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center + schema: + type: string +translations_key_q: + in: query + name: q + description: | + Specify a query to find translations by content (including wildcards). + + *Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).* + + The following qualifiers are supported in the query: + * `id:translation_id,...` for queries on a comma-separated list of translation ids + * `locale.id:locale_id,...` for queries on a comma-separated list of locale ids + * `locale.name:locale_name,...` for queries on a comma-separated list of locale names + * `tags:XYZ` for tags on the translation + * `unverified:{true|false}` for verification status + * `excluded:{true|false}` for exclusion status + * `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries + * `reviewed_after:2013-02-21T00:00:00Z` for fetching translations that were reviewed after the given timestamp + + Find more examples [here](/en/api/strings/usage-examples). + example: PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center + schema: + type: string job_owner: description: filter by user owning job example: abcd1234cdef1234abcd1234cdef1234 diff --git a/paths/translations/index_keys.yaml b/paths/translations/index_keys.yaml index 04ae5c9d3..e8a35f19e 100644 --- a/paths/translations/index_keys.yaml +++ b/paths/translations/index_keys.yaml @@ -28,7 +28,7 @@ parameters: in: query schema: type: string -- "$ref": "../../parameters.yaml#/translations_q" +- "$ref": "../../parameters.yaml#/translations_key_q" responses: '200': description: OK diff --git a/paths/translations/index_locale.yaml b/paths/translations/index_locale.yaml index 7c9526a1c..6ba3c1778 100644 --- a/paths/translations/index_locale.yaml +++ b/paths/translations/index_locale.yaml @@ -29,7 +29,7 @@ parameters: in: query schema: type: string -- "$ref": "../../parameters.yaml#/translations_q" +- "$ref": "../../parameters.yaml#/translations_locale_q" responses: '200': description: OK From 65f1c4e58fb000f8326c57fbbe1c5644b8a60384 Mon Sep 17 00:00:00 2001 From: Mladen Jablanovic Date: Wed, 21 Oct 2026 08:51:18 +0200 Subject: [PATCH 4/4] docs(API): use a state-neutral example for the shared translation query #STRINGS-3829 The shared `translation_query` example selected translations that are already unverified and excluded, so it did not demonstrate the state change for batch unverify and exclude. Use a key and locale filter, which is valid for search and every batch action. Co-Authored-By: Claude Sonnet 5.5 --- doc/compiled.json | 2 +- schemas/translation_query.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 66c2954ac..26c652326 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -3124,7 +3124,7 @@ "translation_query": { "type": "string", "description": "Specify a query to find translations by content (including wildcards).\n\n*Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).*\n\nThe following qualifiers are supported in the query:\n* `id:translation_id,...` for queries on a comma-separated list of translation ids\n* `key.id:key_id,...` for queries on a comma-separated list of translation key ids\n* `key.name:key_name,...` for queries on a comma-separated list of translation key names\n* `locale.id:locale_id,...` for queries on a comma-separated list of locale ids\n* `locale.name:locale_name,...` for queries on a comma-separated list of locale names\n* `tags:XYZ` for tags on the translation\n* `unverified:{true|false}` for verification status\n* `excluded:{true|false}` for exclusion status\n* `updated_at:{>=|<=}2013-02-21T00:00:00Z` for date range queries\n* `reviewed_after:2013-02-21T00:00:00Z` for fetching translations that were reviewed after the given timestamp\n\nFind more examples [here](/en/api/strings/usage-examples).\n", - "example": "PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center" + "example": "key.name:home.title,home.subtitle locale.name:de-DE tags:feature" }, "translation_version": { "type": "object", diff --git a/schemas/translation_query.yaml b/schemas/translation_query.yaml index cfda1b5c3..107056503 100644 --- a/schemas/translation_query.yaml +++ b/schemas/translation_query.yaml @@ -19,4 +19,4 @@ translation_query: * `reviewed_after:2013-02-21T00:00:00Z` for fetching translations that were reviewed after the given timestamp Find more examples [here](/en/api/strings/usage-examples). - example: PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center + example: key.name:home.title,home.subtitle locale.name:de-DE tags:feature