Locale
Locale
A Locale manages the languages of one stack. Each language has a code, such as fr-fr, and can name a fallback language. Entries in the language inherit data from the fallback language until you localize them.
Use this class to
- list every language of a stack
- fetch the details of one language by its code
- add a language, with or without a fallback language
- change the name or fallback language of a language
- delete a language
addHeader
addHeader adds one header to every request of the locale, or replaces the value of an existing one.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header, for example branch. |
| value (required) | String | Value to send in the header. |
Returns: Locale. The same locale, for chaining.
Validation
- There is no client-side validation.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addHeader stores the header in the header map of the locale and sends no request.
- Every request method of the locale sends the map, from find to updateFallback.
- The locale starts with a copy of the stack's headers. addHeader changes only this locale, not the stack or other objects.
- A second call with the same key replaces the value, including a header copied from the stack, such as branch.
Example
Basic usage: list the languages of one branch
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Locale;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class LocaleBranchHeader {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
Locale locales = stack.locale().addHeader("branch", "<BRANCH>");
Response<ResponseBody> response = locales.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addHeaders
addHeaders adds several headers to every request of the locale at once.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, String> | Header names and values to add. |
Returns: Locale. The same locale, for chaining.
Validation
- There is no client-side validation.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addHeaders copies every entry of headers into the header map of the locale and sends no request.
- An entry replaces a header with the same name, including one copied from the stack. Headers with other names stay.
- Every request method of the locale sends the map. The addHeader method adds one header.
- Later changes to your headers map do not reach the locale, because addHeaders copies the entries.
Example
Basic usage: set the token and branch on the locale object
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Locale;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class LocaleHeaders {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
// This stack carries only the api_key header
Stack stack = client.stack("<API_KEY>");
HashMap<String, String> headers = new HashMap<>();
headers.put("authorization", "<MANAGEMENT_TOKEN>");
headers.put("branch", "<BRANCH>");
Locale locale = stack.locale("<LOCALE>").addHeaders(headers);
Response<ResponseBody> response = locale.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addParam
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter, for example include_branch. |
| value (required) | Object | Value of the query parameter, for example true. |
Returns: Locale. The same locale, for chaining.
Validation
- There is no client-side validation.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addParam stores the pair in the query parameter map of the locale and sends no request.
- A second call with the same key replaces the value.
- Only find, fetch and update send the map. create, delete, setFallback and updateFallback send no query parameters.
- The parameter stays on the locale for every later request that sends the map. Use the removeParam method to drop it.
- Get all languages accepts include_count and include_branch. Get a language and Update language accept include_branch.
Example
Basic usage: include the total count of languages
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Locale;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class CountLocales {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
Locale locales = stack.locale().addParam("include_count", true);
Response<ResponseBody> response = locales.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Single language: include the branch key in the response
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Locale;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchLocaleWithBranch {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>", "<BRANCH>");
Locale locale = stack.locale("<LOCALE>").addParam("include_branch", true);
Response<ResponseBody> response = locale.fetch().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}addParams
| Name | Type | Description |
|---|---|---|
| params (required) | HashMap<String, Object> | Query parameter names and values to add. |
Returns: Locale. The same locale, for chaining.
Validation
- There is no client-side validation.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addParams copies every entry of params into the query parameter map of the locale and sends no request.
- An entry replaces a parameter with the same name. Parameters with other names stay.
- Only find, fetch and update send the map. The addParam method lists the parameters each request accepts.
- Later changes to your params map do not reach the locale, because addParams copies the entries.
Example
Basic usage: include the count and the branch key
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Locale;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class LocaleQueryParams {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
HashMap<String, Object> params = new HashMap<>();
params.put("include_count", true);
params.put("include_branch", true);
Locale locales = stack.locale().addParams(params);
Response<ResponseBody> response = locales.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}create
create builds the request that adds a language to the stack, either a supported language or a custom one.
| Name | Type | Description |
|---|---|---|
| body (required) | JSONObject | Language details in a locale object: name, code and an optional fallback. |
Returns: Call<ResponseBody>. The request for the new language, sent when you call execute().
Validation
- There is no client-side validation. create sends body unchanged.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Add a language request (POST /locales) with body as the JSON request body.
- In body, the API expects the language name and code. You can also name the fallback language of the new language in the same object.
- create ignores the code of the object, so call it on stack.locale().
- create sends no query parameters, so include_branch from addParam does not reach this request.
- setFallback sends the same request. Use either method.
- The response body is the raw JSON that the API returns, with the new language.
Example
Basic usage: add French with English as the fallback language
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class CreateLocale {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
JSONObject locale = new JSONObject();
locale.put("name", "docs-test-french-france");
locale.put("code", "fr-fr");
locale.put("fallback_locale", "en-us");
JSONObject body = new JSONObject();
body.put("locale", locale);
Response<ResponseBody> response = stack.locale().create(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}delete
delete builds the request that deletes one language from the stack.
Returns: Call<ResponseBody>. The request for deleting the language, sent when you call execute().
Validation
- Throws IllegalAccessError if the locale has no code, as on stack.locale(), because delete builds the request path from the code. IllegalAccessError is an Error, not an Exception.
- An empty code does not throw. The request reaches the API without a language code in the path.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Delete language request (DELETE /locales/{code}) with the headers of the locale.
- delete sends no query parameters and no request body.
- The response body is the raw JSON that the API returns.
Example
Basic usage: delete a language by code
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Locale;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class DeleteLocale {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
Locale locale = stack.locale("<LOCALE>");
Response<ResponseBody> response = locale.delete().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}fetch
fetch builds the request that retrieves the details of one language by its code.
Returns: Call<ResponseBody>. The request for the language, sent when you call execute().
Validation
- Throws IllegalAccessError if the locale has no code, as on stack.locale(), because fetch builds the request path from the code. IllegalAccessError is an Error, not an Exception.
- An empty code does not throw. The request reaches the API without a language code in the path.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get a language request (GET /locales/{code}) with the headers and query parameters of the locale.
- The API accepts the include_branch query parameter on this request.
- The response body is the raw JSON that the API returns. Read it once with response.body().string().
Example
Basic usage: fetch one language by code
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Locale;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchLocale {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
Locale locale = stack.locale("<LOCALE>");
Response<ResponseBody> response = locale.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Edge case: a locale without a code throws an Error
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Locale;
import com.contentstack.cms.stack.Stack;
public class FetchLocaleWithoutCode {
public static void main(String[] args) {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
Locale locale = stack.locale();
try {
locale.fetch();
} catch (IllegalAccessError e) {
// Fires because stack.locale() holds no language code. catch (Exception e) misses it.
System.out.println("Pass the language code to stack.locale(...)");
}
}
}find
find builds the request that lists every language of the stack, with the language codes.
Returns: Call<ResponseBody>. The request for all languages, sent when you call execute().
Validation
- There is no client-side validation.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get all languages request (GET /locales) with the headers and query parameters of the locale.
- find ignores the language code, so it works on stack.locale() and on stack.locale("<LOCALE>").
- The API accepts the query parameters include_count and include_branch, and a query parameter with a query in JSON format.
- The branch header selects the branch whose languages the API returns.
- The response body is the raw JSON that the API returns. Read it once with response.body().string().
Example
Basic usage: list the languages of a stack
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Locale;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListLocales {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
Locale locales = stack.locale();
Response<ResponseBody> response = locales.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Branch scoping: list the languages of one branch with the count
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Locale;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListBranchLocales {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>", "<BRANCH>");
Locale locales = stack.locale()
.addParam("include_count", true)
.addParam("include_branch", true);
Response<ResponseBody> response = locales.find().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}removeParam
removeParam removes one query parameter from the locale, so later find, fetch and update requests stop sending it.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter to remove. |
Returns: void. This method returns nothing.
Validation
- There is no client-side validation. A key that the locale does not hold leaves the map unchanged and does not throw.
Behavior
- Client-side only. removeParam deletes the entry from the query parameter map of the locale and sends no request.
- removeParam returns void, so it does not chain. Call it as a separate statement.
- Use the addParam method to add the parameter again.
Example
Basic usage: drop the count from later requests
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Locale;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class RemoveLocaleParam {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
Locale locales = stack.locale().addParam("include_count", true);
locales.removeParam("include_count");
Response<ResponseBody> response = locales.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}setFallback
setFallback builds the request that adds a language to the stack with a fallback language.
| Name | Type | Description |
|---|---|---|
| body (required) | JSONObject | Language codes in a locale object, with the fallback language code. |
Returns: Call<ResponseBody>. The request for the new language with its fallback language, sent when you call execute().
Validation
- There is no client-side validation. setFallback sends body unchanged and does not read the code of the object.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Set a fallback language request (POST /locales) with body as the JSON request body.
- This request is the same POST /locales request that create sends, so it adds a new language. To change the fallback language of an existing language, use the updateFallback method.
- The language that you set as a fallback inherits data from the master language when it has no localized version, as the API reference notes.
- setFallback sends no query parameters.
- The response body is the raw JSON that the API returns, with the new language.
Example
Basic usage: add German with English as the fallback language
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class SetFallbackLocale {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
JSONObject locale = new JSONObject();
locale.put("name", "docs-test-german-germany");
locale.put("code", "de-de");
locale.put("fallback_locale", "en-us");
JSONObject body = new JSONObject();
body.put("locale", locale);
Response<ResponseBody> response = stack.locale().setFallback(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}update
update builds the request that changes the display name or the fallback language of one language.
| Name | Type | Description |
|---|---|---|
| body (required) | JSONObject | Updated details in a locale object, for example name. |
Returns: Call<ResponseBody>. The request for the updated language, sent when you call execute().
Validation
- Throws IllegalAccessError if the locale has no code, as on stack.locale(), because update builds the request path from the code. IllegalAccessError is an Error, not an Exception.
- An empty code does not throw. The request reaches the API without a language code in the path.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Update language request (PUT /locales/{code}) with body as the JSON request body.
- update also sends the query parameters of the locale, for example include_branch.
- updateFallback sends a request to the same path without the query parameters.
- The response body is the raw JSON that the API returns, with the updated language.
Example
Basic usage: rename a language and change its fallback language
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Locale;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UpdateLocale {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
JSONObject details = new JSONObject();
details.put("name", "French (France)");
details.put("fallback_locale", "en-us");
JSONObject body = new JSONObject();
body.put("locale", details);
Locale locale = stack.locale("<LOCALE>").addParam("include_branch", true);
Response<ResponseBody> response = locale.update(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}updateFallback
updateFallback builds the request that changes the fallback language of an existing language.
| Name | Type | Description |
|---|---|---|
| body (required) | JSONObject | Updated fallback details in a locale object. |
Returns: Call<ResponseBody>. The request for the updated fallback language, sent when you call execute().
Validation
- Throws IllegalAccessError if the locale has no code, as on stack.locale(), because updateFallback builds the request path from the code. IllegalAccessError is an Error, not an Exception.
- An empty code does not throw. The request reaches the API without a language code in the path.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Update fallback language request (PUT /locales/{code}) with body as the JSON request body.
- The path is the same one that update uses. updateFallback sends no query parameters, while update sends them.
- The response body is the raw JSON that the API returns, with the updated language.
Example
Basic usage: point a language to a new fallback language
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Locale;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UpdateFallbackLocale {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
JSONObject details = new JSONObject();
details.put("code", "<LOCALE>");
details.put("fallback_locale", "en-us");
JSONObject body = new JSONObject();
body.put("locale", details);
Locale locale = stack.locale("<LOCALE>");
Response<ResponseBody> response = locale.updateFallback(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}