====== Domain Translation ======

The header, the menu, the footer, and the pages of a domain can be shown in the viewer's language. It works the same way as [[en:authors_main:game_management:localization|game translations]]: a dictionary of "source → translation" pairs lies beside the text, and the text is substituted when shown. Where there is no translation, the viewer sees the original.

The screen is **"Translation"** in the domain's admin panel ("Translations" in the new admin). It can be opened by a domain admin.

This is only about the text **you** wrote. The engine's own buttons, emails, and interface are translated on their own and have nothing to do with this dictionary.

===== Settings =====

{{ :admin_main:domain_translate_settings_en.png?800 |The "Settings" tab: the domain's language, the translation languages, and what untranslated text falls back to}}

  * **The language the domain is written in** — the language of the original. Until it is chosen, the domain has no localization at all: nothing is substituted and the dictionary is not read.
  * **Translation languages** — checkboxes. Next to each, **"show untranslated as"**: which language to fall back to where a translation is missing. Empty means straight to the base language.
  * The **"Other languages"** row — where to send a viewer whose language the domain does not have.

A fallback may only point at a language the domain has **declared**. Untick a language and everything falling back to it is reset right there on the screen.

> Localization can be switched off ("Localization off") at any time: the substitution stops at once for everybody, and the dictionary stays intact.

===== Pages =====

The **"Pages"** tab lists the domain's pages and asks about each one: is it translated by the dictionary or not.

A page may have a **copy of its own** in another language. Such a copy always **beats the dictionary**: if it exists, the viewer sees it, and the dictionary is not applied to that page. There is no way to turn a copy into dictionary pairs — it is either the copy or the dictionary.

===== Translations =====

The third tab is the table of pairs itself. It is **exactly the same** table as the "Translation" tab of the game editor: the same "untranslated / translated / not translatable" groups, the same filter, the same "do not translate" marks. How it works is described in detail on the [[en:authors_main:game_management:localization#the_translation_tab|Multilingual Game]] page.

There is one difference — the **"What are we translating"** selector in the filter bar:

  * **"Everything at once: the domain and the pages"**;
  * **"Domain: header, menu, footer"**;
  * **"Page ..."** — one at a time.

> **"Everything at once" writes a translation into several dictionaries.** A string that occurs both in the header and on a page is one row of the table, and editing it writes into the dictionary of every place the string occurs in. If a page needs its own wording for the same phrase, narrow "What are we translating" down to that page first.

===== What Gets Translated =====

  * **The domain's name** — in the header and in the browser tab's title.
  * **The site header**, **the site menu**, **the site footer**, **the in-game header** — the html from the [[en:admin_main:domain_menu|"Design" section]].
  * **The domain's pages** — the ones ticked on the "Pages" tab.

Not translated: css, addresses (the domain name, a page's address), mail and payment settings, the engine's own text, and **the content of games** — games have [[en:authors_main:game_management:localization|translations of their own]].

The domain's emails go out with the **base** name, not the translated one.

''{% match lang %}'' templates do not work in the domain design — that is a device for tasks.

===== Text Inside Scripts: gt() =====

The domain menu is a script, and the button captions in it are plain strings. To let the engine see them, wrap each one in ''gt()'':

<code JavaScript>
add_navbar({
  items: [
    {name: gt('ИГРЫ'), url: 'index.php'},
    {name: gt('АРХИВ'), url: 'archive.php'},
  ],
  ...
});
</code>

The caption then shows up in the translation table as an ordinary string, and the translation is substituted **on the server**, before the page reaches the viewer.

  * ''gt()'' takes **the string right inside the brackets**, in quotes. ''gt(x)'' and ''gt('A' + b)'' are left alone by the engine — they stay as they are and return their own value.
  * Strings with no letters (digits, punctuation) are not translated.
  * Captions **without** ''gt()'' simply never reach the table, and nobody warns you.

This works in any html block of the design, not only in the menu.

===== JSON: Export and Import =====

The **"JSON"** button at the top of the screen:

  * **Download everything** — a snapshot of the whole dictionary, all languages.
  * **Download the untranslated** — a file for a translator: only what is left.
  * **Download (language)** and **Download the untranslated (language)** — the same for one language.
  * **Load from a file**, **Copy to the clipboard**, **Paste from the clipboard**.

Loading **does not save**: it edits the screen, and it is the **"Save"** button that writes. The browser will not let you leave the page with unsaved changes in silence — it asks.

Loading **merges rather than replaces**: pairs are applied one by one. An empty translation in the file means "remove this pair".

Both kinds of file are accepted — the full snapshot and the translator's file.

===== A New Domain =====

A new domain **inherits** the base domain's dictionary — as a copy, once, at the moment of creation. Later edits to the base domain's dictionary never reach it.

A new domain has a name of its own, so the inherited translation of the old name arrives in **"Outdated translations"**, and the new name stays untranslated.

===== Worth Knowing =====

  * **Editing the original detaches its translation.** Change the text in the design and its translation goes into "Outdated translations", where it can be re-attached or deleted. Rolling the design back in the studio does not roll the dictionaries back.
  * **The source is the saved design, not a draft.** If you have edited the header in the studio, save it first, then reload this screen.
  * **One "Save" writes several things at once** — the languages, the page marks, and the dictionaries. If something did not get written, the red bar lists it all together.
  * **A row that is untranslated and unmarked is not stored at all** — the dictionary never holds empty pairs.
  * **A translation that drops or invents a substitution** (''!username!'' and the like) is not saved: the engine says so.

===== The Old Way: addTranslation() =====

Menu captions used to be translated in the browser, by a call in the menu block itself:

<code JavaScript>
addTranslation('en', 'АВТОРАМ', 'ABOUT');
</code>

**It still works**, and running domains are not deprived of it. But it covers only the menu button captions — not the header, not the footer, not the pages — and it says nothing about what is still untranslated.

There will be no double translation: if the server has already translated a string, what reaches the browser is the English one, and ''addTranslation'' simply does not find it.

For a new domain use ''gt()'' and this page.

===== See Also =====

  * [[en:admin_main:domain_menu|Domain Menu Setup]] — how the menu block is built.
  * [[en:authors_main:game_management:localization|Multilingual Game]] — game translations; the table is the same one.