Locale

View as Markdown

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.

NameTypeDescription
key (required)String

Name of the header, for example branch.

Default: Not applicable
value (required)String

Value to send in the header.

Default: Not applicable

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.

NameTypeDescription
headers (required)HashMap<String, String>

Header names and values to add.

Default: Not applicable

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

addParam adds one query parameter to the locale, for the find, fetch and update requests.

NameTypeDescription
key (required)String

Name of the query parameter, for example include_branch.

Default: Not applicable
value (required)Object

Value of the query parameter, for example true.

Default: Not applicable

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

addParams adds several query parameters to the locale at once, for the find, fetch and update requests.

NameTypeDescription
params (required)HashMap<String, Object>

Query parameter names and values to add.

Default: Not applicable

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.

NameTypeDescription
body (required)JSONObject

Language details in a locale object: name, code and an optional fallback.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Name of the query parameter to remove.

Default: Not applicable

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.

NameTypeDescription
body (required)JSONObject

Language codes in a locale object, with the fallback language code.

Default: Not applicable

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.

NameTypeDescription
body (required)JSONObject

Updated details in a locale object, for example name.

Default: Not applicable

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.

NameTypeDescription
body (required)JSONObject

Updated fallback details in a locale object.

Default: Not applicable

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());
    }
}