Repository navigation
Conversation
…#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 <noreply@anthropic.com>
Contributor
API changelog (oasdiff)Doc-only edits (descriptions, examples) do not appear here. |
…S-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 <noreply@anthropic.com>
…tes #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 <noreply@anthropic.com>
jablan
requested review from
Mikko Karkee (Varpuspaavi) and
Sven Dunemann (forelabs)
and
a balanced review from Copilot
October 19, 2026 13:11
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The shared example selects translations already in the target state for batch unverify and exclude.
1 open issue
What changed in this PR
Documents existing key and locale query qualifiers in the translation API and consolidates reusable query documentation.
Changes:
- Adds key/locale qualifiers and clarifies translation IDs.
- Shares query definitions across listing, search, and batch endpoints.
- Updates examples and regenerates the compiled specification.
| File | Description |
|---|---|
| schemas/translation_query.yaml | Defines the shared request-body query schema. |
| schemas.yaml | Registers the query schema. |
| paths/translations/search.yaml | References the shared query schema. |
| paths/translations/index.yaml | References the project query parameter. |
| paths/translations/index_locale.yaml | References the locale-scoped query parameter. |
| paths/translations/index_keys.yaml | References the key-scoped query parameter. |
| paths/translations/batch_verify.yaml | Reuses the shared query schema. |
| paths/translations/batch_unverify.yaml | Reuses the schema and adds a key-filter example. |
| paths/translations/batch_unreview.yaml | Reuses the shared query schema. |
| paths/translations/batch_review.yaml | Reuses the shared query schema. |
| paths/translations/batch_include.yaml | Reuses the shared query schema. |
| paths/translations/batch_exclude.yaml | Reuses the shared query schema. |
| parameters.yaml | Adds three route-specific query parameters. |
| doc/compiled.json | Includes regenerated definitions and references. |
Review effort: Balanced
| * `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 |
There was a problem hiding this comment.
jablan I think this is valid, adjust the example so its "valid" for each of the usages
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
qparameter oftranslationsindex/search and the batch actions already supportskey.id,key.name,locale.idandlocale.name(comma-separated lists), but onlyid(translation ids),tags,unverified,excludedand the date qualifiers were documented. The only documented way to act on the translations of specific keys was to look up translation ids first (one request per key) and then pass them on.With these qualifiers a single request is enough, for example:
Changes
key.id,key.name,locale.idandlocale.namein theqdescription, and clarify thatid:takes translation ids.parameters.yaml#/translations_q: query parameter of translations index on the project route.parameters.yaml#/translations_locale_qand#/translations_key_q: the same for the locale and key routes, without the qualifiers those routes already fix (locale.*andkey.*respectively).schemas/translation_query.yaml(registered inschemas.yaml):qproperty of the request body of translations search and the batch actions (verify,unverify,review,unreview,exclude,include).verified:true).key.idexample to the batch unverify description.doc/compiled.json.Description-only change, no schema change.
Testing
make lintpasses.key.idandlocale.idlists on search and on batch unverify (project and locale routes), andkey.name/locale.namelists on search.🤖 Generated with Claude Code