docs(API): clarify locale_ids vs default_locale_codes in PATCH member docs - #1264
Merged
Merged
Conversation
…codes (account-level) in PATCH member docs
The request body schema for PATCH /accounts/{account_id}/members/{id}
described locale_ids and default_locale_codes with near-identical
wording, and the endpoint description only mentioned locale_ids. This
made it easy to assume locale_ids grants account-wide language access,
when it is actually project-scoped and only takes effect alongside
project_ids/strategy. default_locale_codes is the account-level field
("Language access" in the translator profile UI) that applies across
all of the user's projects.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
API changelog (oasdiff)Doc-only edits (descriptions, examples) do not appear here. |
Sven Dunemann (forelabs)
changed the title
Sven Dunemann (forelabs)
approved these changes
Sep 14, 2026
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
1 participant
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.
What changed
PATCH /accounts/{account_id}/members/{id}docs did not distinguishlocale_ids(project-scoped) fromdefault_locale_codes(account-level). Both fields had near-identical wording in the request body schema, and the endpoint-level description only mentionedlocale_ids, making it easy to mistake it for the account-wide option.locale_ids: now states it is project-scoped and must be paired withproject_ids(andstrategy) to take effect.default_locale_codes: now states it is the account-level field corresponding to "Language access" in the translator profile UI, applied across all of the user's projects.default_locale_codesfor account-wide language access.Why
An agent session used
locale_idsalone to try to grant account-wide language access, then incorrectly reported the permission as "granted at account level." Nothing in the spec surfaced the project-scoped vs. account-level distinction.How to test
npx swagger-cli validate main.yaml— passes.make bundleregenerateddoc/compiled.jsonto reflect the updated descriptions (tmp/compiled.yamlis gitignored build output).bash ./lint.sh— no validation errors.