---
source: https://carbone.io/documentation/design/advanced-features/translations-i18n.html
title: "How to translate text in your template?"
description: "How to translate text in your template?"
generated_at: "2026-07-13"
---

# Translations i18n

How to translate text in your template?  
COMMUNITY FEATURE Available for:  
✓ Carbone Cloud  
✓ Carbone On-premise  
✓ Embedded Carbone JS   v2.0+ 

## 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)](/documentation/design/formatters/number.md#formatn-precision), [:formatD](/documentation/design/formatters/date.md#formatd-patternout-patternin), [:formatC](/documentation/design/formatters/currency.md#formatc-precisionorformat-targetcurrency), and [:formatI](/documentation/design/formatters/interval.md#formati-patternout-patternin) 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 their 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 does 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**

```cdata
"data"         : {},
"convertTo"    : "pdf",
"lang"         : "fr-fr", // target lang of the report
"translations" : {
  "fr-fr" : {  // localization dictionary for fr-fr
    "apples"  : "Pommes",
    "meeting" : "rendez-vous",
    "monday"  : "lundi",
    "tuesday" : "mardi",
  },
}
```

```ctemplate
{t(meeting)}
{t(apples)}
{d.id:ifEQ(2):show( {t(monday)} ):elseShow( {t(tuesday)} )}
```

```cresult
rendez-vous
pommes
lundi
```

## 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**

```cdata
"data"         : {
  "id"        : 2
  "tool"      : "key1",
  "protection": "key2"
},
"convertTo"    : "pdf",
"lang"         : "en-us", // target lang of the report
"translations" : {
  "fr-fr" : {
    "key1" : "Tournevis",
    "key2" : "Gants",
    "key3" : "Professionel",
    "key4" : "Particulier"
  },
  "en-us" : {
    "key1" : "Screwdrivers",
    "key2" : "Gloves",
    "key3" : "Professional",
    "key4" : "Individual"
  }
}
```

```ctemplate
{d.tool:t}
{d.protection:t}
{d.id:ifEQ(2):show("key3"):elseShow("key4"):t}
```

```cresult
Screwdrivers
Gloves
Professional
```

## 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.

```json
"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-gb
    "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:

```js
  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:

```bash
# 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.

> ℹ️ **Note:** The Carbone Studio will soon provide a better tool for this purpose.

## Related topics

- [Transform](/documentation/design/advanced-features/transform.md)
- [Digital signatures](/documentation/design/advanced-features/signatures.md)
- [Pictures](/documentation/design/advanced-features/pictures.md)
- [Pagination](/documentation/design/advanced-features/pagination.md)
- [Key-value mapping](/documentation/design/advanced-features/key-value-mapping.md)
- [Hyperlinks](/documentation/design/advanced-features/hyperlinks.md)