Guide

Translations

Translations let one template print its fixed wording in several languages. Each piece of wording is a key — greeting, footer.thanks — bound in a field as {{ $t.greeting }}, with a text for every language.

What translations are for — in plain words

Some wording is the same on every document but must change with the language: "Invoice", "Due date", "Thank you for your order". That is what translations are for. You give each piece of wording a short name (a key, such as invoiceTitle) and write its text once per language. The template then prints the text in whichever language the document is made in.

This is different from your data, which is what changes from one document to the next (the customer's name, the amounts). A customer's name is data and is never translated; "Due date" is translation and never changes with the customer. A single sentence can use both, as the greeting example below shows. See Fields and bindings for data.

A worked example: an invoice in English and Latvian

Open Manage template data (the database button in the toolbar) and choose Translations.
Add English and Latvian. The first one added becomes the fallback language.
Press Add key and add invoiceTitle. Choose Language: English and type "Invoice"; choose Latvian and type "Rēķins". Add dueDate ("Due date" / "Apmaksas termiņš") the same way.
In the invoice, wherever a heading says "Invoice", replace the typed word with {{ $t.invoiceTitle }}. The label "Due date" becomes {{ $t.dueDate }}. ($t is the advanced syntax for "the translated text"; the editor's field dialogs and the Keys view do the typing.)
On the Document tab, choose the Translation language — Latvian — and the page now reads "Rēķins" and "Apmaksas termiņš", with the numbers and dates still coming from your data.

Generating through the API, you pick the language per request with its language field (see Document settings).

Where to find it

Open Manage template data (the database button in the editor toolbar) and choose the Translations tab.

Adding a language

Type in Add a language: an English name such as Latvian or Spanish, or a language code such as lv, es or pt-BR. Pick the match, or press Enter to add the first one. Every official EU language, and a number of others, can be found by name; any other real language can be added by its code. A language the template already has is listed as already added, and a code that names no real language is not offered.

On a template with no translations yet, the first language you add becomes the fallback language.

Languages are stored as full language codes — de, de-CH, pt-BR, sr-Latn. Search by the language's name, by a region ("swiss", "Switzerland") or by the code ("de-CH" finds German (Switzerland)); the plain language is listed first, then its regions. A region is its own language: German (Switzerland) can sit next to German and German (Austria) in one template, each with its own texts. The old three-letter codes (eng, ger, fre, ita) are no longer accepted — use en, de, fr, it.

When a document asks for a language the template only has without the region (for example de-CH when the template has de), the plain language is used. A different region is never used instead (de-AT does not answer for de-CH), and the plain language is never answered by a regional entry.

Translating keys

The Keys view lists every key that any language has. Choose the language to edit in Language, then type its text next to each key. The Language list also shows how many keys each language has not translated.

Where the language you are editing has no text of its own for a key, the row says what the document prints instead:

Uses the fallback language — the box shows the fallback text in grey, and that is what prints.
Missing — prints blank — nothing prints for this key in this language: the fallback has no text for it either, or it sits in a group this language only partly has (see The fallback language below).
Blank on purpose — this language has the key with an empty text, so nothing prints and the fallback is not used.

In any language other than the fallback, the arrow button next to a translated key removes that language's own text, so the fallback text prints again. The bin button deletes the key from every language.

Add key adds a new key with its text in the language you are editing. Use dots to group keys: footer.thanks is bound as {{ $t.footer.thanks }}. Any character other than an English letter, a digit or an underscore becomes an underscore.

Fields inside a text

A text can hold fields. Give greeting the English text Hello, {{ $data.customer.name }}! and the Latvian text Sveiki, {{ $data.customer.name }}!, bind a block to {{ $t.greeting }}, and the document prints the customer's name inside the greeting, in whichever language it renders — in the editor, PDF, HTML and Word alike.

A field inside a text works exactly as it would typed straight into the block that shows the text:

It reads the same data. In a repeated block it reads the current record, and in a header or footer Page {{ $page.number }} of {{ $page.count }} prints the real page numbers.
format and formatDate follow the document's date/number locale and currency.
A value the data does not have prints blank, and is reported as a missing field, the same as anywhere else.
A value is printed as it is. If a customer's name happens to contain {{ }}, those characters print; they are never treated as another field.

A text can also use another text: Thank you from {{ $t.company }} prints the company text. That only works when the other text is plain words. If it has fields of its own, it is not filled in, so that part prints nothing. The same goes for a {{ }} that is empty or cannot be read. A {{ with no closing }} prints exactly as typed from there on. The Keys view flags each of these on its row, and a preview or download reports them as expressions that could not be worked out.

Texts inside a list, edited in the JSON view, are filled in the same way, one by one. A {{ $page.number }} in one prints the page that item lands on, even when the Repeater, List or table showing the list runs over several pages.

The fallback language

Choose it in Fallback language. When a document renders in a language that has no text for a key, the fallback language's text is printed instead.

The fallback fills in whole keys at the top level only. If a language has some keys of a group — say footer.line1 — but not others, the ones it leaves out print blank instead of falling back, and the Keys view marks them Missing. Give the language every key of the group, or none of them.

The fallback language cannot be removed while other languages remain: choose another fallback first. Removing the last language removes translations from the template.

Which language a document prints in

That is chosen in the Document tab of the side panel — see Document settings. If the template no longer has the language chosen there, the document goes back to choosing its language automatically.

JSON

Switch from Keys to JSON to edit one language's texts directly — for example values that are not plain text, such as numbers or lists, which the Keys view shows but does not edit. JSON that is not valid is never saved: the last valid texts keep rendering until it is fixed.

Duplicate and unrecognised entries

A template saved with two entries that have the very same code keeps both, and the editor flags the second one: a document always uses the first. A code the editor does not recognise is kept and flagged too; it is still used when a document asks for exactly that code.

Languages written in other scripts

Any language can be added, and nothing is ever refused because of the script it is written in. What each output does with a script was measured by rendering real text in it — PDF as we produce it, HTML in Chrome, and Word files opened in LibreOffice:

Latin, Cyrillic and Greek print correctly in PDF, HTML and Word.
Arabic and Hebrew: the letters print, joined, and each word reads correctly. PDF prints a phrase of two or more words in the wrong order; HTML and Word order the words correctly. Every output lays paragraphs out left to right — there is no right-to-left paragraph setting yet — so punctuation or digits at the start or end of an Arabic or Hebrew sentence, or a Latin name inside it, land on the wrong side. In PDF, Arabic prints only in a sans-serif font, and Hebrew only in a sans-serif font or Times New Roman; in any other font they print as empty boxes. In a PDF table cell, a line that starts with Latin text prints its Arabic or Hebrew letters backwards.
Chinese, Japanese and Korean: PDF output has no font for them, so they print as empty boxes. HTML and Word draw them with the reader's own fonts. In HTML, a paragraph long enough to wrap needs more room than the layout gives it and runs into what follows, and Japanese kanji may be drawn from a Chinese font.
Hindi (Devanagari) and Thai: PDF output has no font for them, so they print as empty boxes. HTML and Word have not been checked yet.

The editor shows the relevant sentence next to each such language, and a preview or download says so whenever a file it produced has one of these problems.

No machine translation

You type every text. Nothing is translated automatically, and no text is sent to a translation service.

If something looks wrong

A heading shows the key's name or prints blank. The key is spelled differently in the block and in the Keys view, or this language has no text for it and neither does the fallback language. The row in the Keys view says Missing — prints blank.
The wrong language prints. The language is chosen on the Document tab (or, for the API, by the request). Left on automatic, it follows the Date/number locale; set it explicitly instead.
Dates and numbers did not change language. They follow the Date/number locale, not the translation language. The two are independent.
A greeting lost the customer's name. The name is data, so write it as a field inside the translated text (Hello, {{ $data.customer.name }}!), in every language.
A sentence uses another text and prints nothing in that spot. The other text has fields of its own; only plain words can be reused.
Chinese, Japanese, Hindi or Thai prints as empty boxes in the PDF. See Languages written in other scripts above.