Translations i18n

Overview

Carbone can generate documents in any language. You have two options:

1. Create one template per language.
2. Create a multi-language template with a separate localization dictionary to translate all sentences in the template.

Creating a multi-language template requires the following:

1. Use :formatN(L), :formatD, :formatC, and :formatI to format numbers, dates, intervals, and prices. Carbone will automatically adapt the printed values according to the lang option used when the report is generated (en-us, en-gb, ...)
2. Use the special tag {t( )} for all static text (text not coming from the JSON data) or the formatter :t for text coming from data.

When the report is rendered, all text between {t( )} is replaced with its corresponding translation found in a separate localization dictionary. Carbone automatically selects the localization dictionary that matches the lang attribute (en-us, en-gb, etc.). If a translation key is not found, Carbone prints the key in the final report.

Important Notes:

• {t( )} tags can be placed anywhere, even inside formatters, such as {d.id:ifEQ(2):show({t(monday)})}.
• {t( )} tags do not require quotes to preserve whitespace, e.g., {t(all whitespace is preserved without quotes)}.

i18n Localization dictionary

The localization dictionary must be provided to Carbone when rendering the report. The method for doing this varies depending on the Carbone distribution:

With the HTTP API (Carbone Cloud and On-Premise EE)

Here is an example of an HTTP body showing how to send the localization dictionary.

"data"         : {},
"convertTo"    : "pdf",
"lang"         : "en-us", // target lang of the report
"translations" : {
  "en-us" : {             // localization dictionary for en-us
    "frites"     : "French fries",
    "Monsieur X" : "John Doe"
  },
  "en-gb" : {             // localization dictionary for en-gn
    "frites": "chips"
  }
}

With local files (Carbone On-Premise EE or Carbone Embedded CE)

On startup, Carbone loads all JSON files found in the lang subdirectory of the templatePath. This template path can be modified in the configuration of Carbone (templatePath)

Here is an example of the expected contents of localization dictionary files (JSON) on disk:

  templatesPath
    |- lang
      |- en-us.json : { "frites" : "French fries", "Monsieur X" : "John Doe"}
      |- en-gb.json : { "frites" : "chips" }

How to generate the dictionary?

You can use the following CLI tools to find all {t( )} tags in your templates and create or update the localization dictionary:

# On-Premsie Enterprise Edition
./carbone-ee translate --lang en-us --path /var/lib/all-my-templates
# Community Edition
./node_modules/.bin/carbone translate --lang en-us --path /var/lib/all-my-templates

In both cases, Carbone parses all templates found in the --path directory and creates or updates the JSON file named --lang in the lang subdirectory of the template path.

The Carbone Studio will soon provide a better tool for this purpose.

Translation Example

The following example is a report translated into French. It is possible to embed translation tags within other tags.

HTTP Body