Locale
Locale
A locale is a language that a stack publishes content in, such as en-us or fr-fr. The Locale class manages the languages of one stack through the Content Management API (CMA). Use this class to
- list the languages of a stack
- add a language, with an optional fallback language
- read, rename, change the fallback of, or delete one language
Call the locale method of the Stack class to get an object.
Instance State
- Call stack.locale() without a code to work with the collection, for example create and query.
- Call stack.locale('<LOCALE>') with a language code to work with one language, for example fetch and update.
- Each form has only its own request methods. fetch is undefined on stack.locale(), and create is undefined on stack.locale('<LOCALE>'), so calling the wrong one throws TypeError.
- The factory takes the language code, such as fr-fr, not a UID. The request path uses the code.
Warning stack.locale('') returns the collection form, because the SDK treats an empty string as no code. Check the code before you build the object.
Class-Level Notes
Branch scoping.
- When you create the stack with branch_uid, every request from this class sends the branch header, and the API works with the languages of that branch.
Headers.
- Every request sends the headers of this object, which start as a copy of the stack headers. Change them with addHeader, addHeaderDict and removeHeader.
Rate limiting and retry.
- This SDK automatically retries on 429 with configurable delay and attempt limits.
Additional Resource For more information on the retry options and their defaults, refer to the Contentstack documentation.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| List the languages with fetchAll | No | Use query and call find() |
| Set a fallback language with its own method | No | Pass fallback_locale to create, or change it with update |
Method Index
Work with the collection. Available on stack.locale().
| Method Name | Returns | Description |
|---|---|---|
| create | The new locale. | Adds a language to the stack. |
| query | A query for locales, sent when you call find(), findOne() or count(). | Builds a language query. |
Work with one language. Available on stack.locale('<LOCALE>').
| Method Name | Returns | Description |
|---|---|---|
| fetch | The requested locale. | Retrieves one language. |
| update | The updated locale. | Saves changes to one language. |
| delete | The API response with a notice. | Deletes one language. |
Set request headers. Available on both forms.
| Method Name | Returns | Description |
|---|---|---|
| addHeader | The same locale object, for chaining. | Adds one request header. |
| addHeaderDict | The same locale object, for chaining. | Adds several request headers. |
| removeHeader | The same locale object, for chaining. | Removes one request header. |
Class-Level Snippet
The snippet below lists the languages of a stack and prints the code and fallback language of each one.
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const result = await stack.locale().query().find()
for (const locale of result.items) {
console.log(locale.code, locale.name, locale.fallback_locale)
}
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}Methods
Each method of the Locale class has its own section below, with its parameters, validation rules, behavior, and examples.
addHeader
addHeader adds one header to every request that this locale object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Header name, for example x-request-id. |
| value (required) | string | Header value to send. |
Returns: Locale. The same locale object, for chaining.
Validation
- There is no client-side validation. A null or undefined key leaves the headers unchanged, and addHeader returns the same object.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeader sends no request.
- The first header change on this object copies the headers that it inherited from the stack. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
- Every request method of this object sends its headers. The objects that those methods return carry the same headers.
- query() copies the headers at the moment you call it. Change the headers first, then call query().
- A key that the object already holds gets the new value.
Example
Basic usage: tag the requests of one locale object
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const locale = stack.locale('<LOCALE>').addHeader('x-request-id', 'docs-123')
// Every request this object sends from now on carries the header
console.log(locale.stackHeaders['x-request-id'])addHeaderDict
addHeaderDict adds several headers at once to every request that this locale object sends.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
Returns: Locale. The same locale object, for chaining.
Validation
- There is no client-side validation. A null value, or a value that is not an object, leaves the headers unchanged, and addHeaderDict returns the same object.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeaderDict sends no request.
- The first header change on this object copies the headers that it inherited from the stack. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
- Every request method of this object sends its headers. The objects that those methods return carry the same headers.
- query() copies the headers at the moment you call it. Change the headers first, then call query().
- addHeaderDict merges headerDict into the headers of the object. A key that the object already holds gets the new value.
Example
Basic usage: add two tracing headers
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const locale = stack.locale().addHeaderDict({
'x-request-id': 'docs-123',
'x-trace-id': 'trace-456'
})
console.log(locale.stackHeaders['x-request-id'], locale.stackHeaders['x-trace-id'])create
create adds a new language to the stack.
| Name | Type | Description |
|---|---|---|
| data (required) | { locale: LocaleData } | Request body, with the language under the locale key. |
| data.locale.code (required) | string | Language code, for example fr-fr. |
| data.locale.name | string | Display name of the language. |
| data.locale.fallback_locale | string | Code of the language to inherit content from. |
| param | object | Query parameters, sent as given. |
| param.include_branch | boolean | Adds the _branch key to the response. |
Returns: Promise<Locale>. The new locale.
Validation
- There is no client-side validation. create sends data as given and does not check its keys.
- create exists only on stack.locale(). On stack.locale('<LOCALE>') it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends POST /v3/locales with data as the JSON body and every key of param as a query parameter, as Add a language describes.
- The SDK does not wrap data. Put the language under the locale key yourself.
- With fallback_locale, the same request sets the fallback language, as Set a fallback language describes. Entries in the new language then inherit data from the fallback language instead of from the master language.
- Resolves to a Locale object that the SDK builds from the locale key of the response, with fetch, update and delete.
Example
Basic usage: add a language
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const locale = await stack.locale().create({ locale: { code: 'fr-fr', name: 'docs-test-french' } })
console.log(locale.code, locale.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: add a language with a fallback language on a branch
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
const data = {
locale: {
code: 'fr-ca',
name: 'docs-test-french-canada',
fallback_locale: 'fr-fr'
}
}
try {
const locale = await stack.locale().create(data, { include_branch: true })
console.log(locale.code, locale.fallback_locale, locale._branch)
} catch (error) {
console.error(error.errorMessage)
}delete
delete removes the language whose code you passed to stack.locale('<LOCALE>') from the stack.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
Returns: Promise<Response>. The API response with a notice.
Warning A successful delete removes the language from the stack, and you cannot undo it. To use the language again, add it with create.
Validation
- There is no client-side validation.
- delete exists only on stack.locale('<LOCALE>') and on the Locale objects that fetch, create and query return. On stack.locale() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends DELETE /v3/locales/{code} with every key of param as a query parameter, as Delete language describes.
- Resolves to the response body, which carries notice. When the API answers with an empty body, it resolves to { status, statusText } instead.
Example
Basic usage: delete one language
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const response = await stack.locale('<LOCALE>').delete()
console.log(response.notice)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: pass query parameters with the request
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
// Query parameters to send with the request
const param = {}
try {
const response = await stack.locale('<LOCALE>').delete(param)
console.log(response.notice)
} catch (error) {
console.error(error.errorMessage)
}fetch
fetch retrieves the language whose code you passed to stack.locale('<LOCALE>').
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.include_branch | boolean | Adds the _branch key to the response. |
Returns: Promise<Locale>. The requested locale.
Validation
- There is no client-side validation.
- fetch exists only on stack.locale('<LOCALE>'). On stack.locale() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/locales/{code} with every key of param as a query parameter, as Get a language describes.
- Resolves to a new Locale object that holds the language fields, with fetch, update and delete. The object you called fetch on does not change.
Example
Basic usage: read one language
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const locale = await stack.locale('<LOCALE>').fetch()
console.log(locale.code, locale.name, locale.fallback_locale)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: read a language on a branch
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
try {
const locale = await stack.locale('<LOCALE>').fetch({ include_branch: true })
console.log(locale.code, locale._branch)
} catch (error) {
console.error(error.errorMessage)
}query
query builds a request for the languages of the stack. It sends nothing until you call a method of the returned query.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters for the request. |
| params.query | object | Condition on language fields, sent as JSON. |
| params.include_count | boolean | Adds the total number of languages. |
| params.include_branch | boolean | Adds the _branch key to each language. |
Returns: Query. A query for locales, sent when you call find(), findOne() or count().
Validation
- There is no client-side validation.
- query exists only on stack.locale(). On stack.locale('<LOCALE>') it is undefined, and calling it throws TypeError.
- An invalid value surfaces as a rejected promise from the request method you call next.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. query copies the headers of this object and params, and returns a Query object.
- find and findOne send GET /v3/locales and resolve to Locale objects, as Get all languages describes. count resolves to the response body, which holds the number of matching languages.
- The SDK sends params.query as query=<JSON>, and every other key of params as a query parameter.
- stack.locale() has no fetchAll. Call query().find() to list every language.
Example
Basic usage: list every language of a stack
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const result = await stack.locale().query().find()
for (const locale of result.items) {
console.log(locale.code, locale.name)
}
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: find the languages that fall back to one language, with a count
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
try {
const result = await stack.locale()
.query({ query: { fallback_locale: 'fr-fr' }, include_count: true, include_branch: true })
.find()
console.log(result.count)
for (const locale of result.items) {
console.log(locale.code, locale._branch)
}
} catch (error) {
console.error(error.errorMessage)
}removeHeader
removeHeader removes one header from the requests that this locale object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
Returns: Locale. The same locale object, for chaining.
Validation
- There is no client-side validation. A null or undefined key, or a key that the object does not hold, leaves the headers unchanged, and removeHeader returns the same object.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. removeHeader sends no request.
- The first header change on this object copies the headers that it inherited from the stack. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
- Every request method of this object sends its headers. The objects that those methods return carry the same headers.
- query() copies the headers at the moment you call it. Change the headers first, then call query().
- removeHeader can remove a header that the object inherited from the stack, such as branch. The stack and its other objects keep that header.
- Do not remove api_key. Without it, the API cannot tell which stack the request is for.
Example
Basic usage: drop a header that you added earlier
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const locale = stack.locale('<LOCALE>')
.addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'trace-456' })
.removeHeader('x-trace-id')
console.log('x-trace-id' in locale.stackHeaders) // falseupdate
update saves the current properties of the locale object to the language, such as its name and fallback language.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.include_branch | boolean | Adds the _branch key to the response. |
Returns: Promise<Locale>. The updated locale.
Validation
- There is no client-side validation.
- update exists only on stack.locale('<LOCALE>') and on the Locale objects that fetch, create and query return. On stack.locale() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends PUT /v3/locales/{code} with every key of param as a query parameter, as Update language and Update fallback language describe.
- The body is { locale: { ... } } with every data property of the object, including code. The SDK leaves out uid, urlPath, stackHeaders, api_key, org_uid and the created_*, updated_* and deleted_at fields.
- update sends what the object holds, not only what you changed. Call fetch first, then change the properties and call update.
- The request path keeps the code that you passed to stack.locale('<LOCALE>'), even when you change code on the object.
- Resolves to a new Locale object that the SDK builds from the response.
Example
Basic usage: change the fallback language
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const locale = await stack.locale('<LOCALE>').fetch()
locale.fallback_locale = 'en-us'
const updated = await locale.update()
console.log(updated.code, updated.fallback_locale)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: rename a language on a branch
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
try {
const locale = await stack.locale('<LOCALE>').fetch()
locale.name = 'French (France)'
const updated = await locale.update({ include_branch: true })
console.log(updated.name, updated._branch)
} catch (error) {
console.error(error.errorMessage)
}