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 the special tag {t( )} for static text or/and the formatter :t for dynamic text coming from the JSON data-set.
2. 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, ...)

When the report is rendered, all tags chained with the formatter :t, and all the text between {t( )} are 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.

Static Translation

Use the {t( )} tag to translate static content, such as: titles, headers, and text not coming from the JSON data-set.

The translation tag {t( )} has special properties:

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

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

HTTP Body

Dynamic Translation

Use the :t formatter to translate Carbone tags.

Text passed to :t is replaced with translations from a localization dictionary based on the lang attribute (e.g., en-us, fr-ca). If a translation key is missing, the original text is used in the final report.

HTTP Body

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.