Skip to content

v3/languages: state that we follow BCP 47 for lang codes #288

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
daniel-jones-dev wants to merge 1 commit into
base: main
Choose a base branch
from
+7 −2
Open

v3/languages: state that we follow BCP 47 for lang codes #288

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions api-reference/languages/retrieve-supported-languages-by-product.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,11 @@ User-Agent: YourApp/1.2.3
]
```

## Language codes

Language codes in the `lang` field follow [BCP 47](https://www.rfc-editor.org/rfc/rfc5646). The base language
subtag is always present; script, region, and variant subtags are included where needed to distinguish variants.

## Product features

Each language object includes a `features` array indicating which optional capabilities are supported for that language
Expand Down Expand Up @@ -222,7 +227,7 @@ The v3 language endpoints are designed to be forward-compatible:
- Existing fields will not be removed or changed in backwards-incompatible ways

<Info>
Build your integration to gracefully handle new values in the `features` array.
Build your integration to gracefully handle new BCP 47 `lang` codes and new values in the `features` array.
</Info>

## Best practices
Expand All @@ -231,6 +236,6 @@ The v3 language endpoints are designed to be forward-compatible:

2. **Check features**: Always check the `features` array on language objects rather than assuming support (e.g. for formality, glossary use, or writing style).

3. **Handle forward compatibility**: Ignore unknown values in the `features` array to remain compatible as new capabilities are added.
3. **Handle forward compatibility**: Ignore unknown values in the `features` array and unknown `lang` codes to remain compatible as new languages and capabilities are added.

4. **Use specific variants**: For target languages, prefer specific regional variants (e.g., `"en-US"`, `"en-GB"`) when the distinction matters to your users.