docs(API): document key and locale query qualifiers for translations #STRINGS-3829

parameters.yaml

@@ -286,6 +286,74 @@ 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
+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

paths/translations/batch_exclude.yaml

@@ -59,22 +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 ids
-              * `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

paths/translations/batch_include.yaml

@@ -59,21 +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 ids
-              - `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

paths/translations/batch_review.yaml

@@ -61,20 +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 ids
-              * `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'

paths/translations/batch_unreview.yaml

@@ -60,19 +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 ids
-              * `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'

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
@@ -61,21 +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 ids
-              * `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

paths/translations/batch_verify.yaml

@@ -65,19 +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 ids
-              * `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'

paths/translations/index.yaml

@@ -44,26 +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 ids
-    * `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

paths/translations/index_keys.yaml

@@ -28,23 +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 ids
-    * `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_key_q"
 responses:
   '200':
     description: OK

paths/translations/index_locale.yaml

@@ -29,24 +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 ids
-    - `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_locale_q"
 responses:
   '200':
     description: OK

paths/translations/search.yaml

@@ -73,20 +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 ids
-              - `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'

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:

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