Manual
Manual
Languages and strings
A game can be shown in more than one language. This page covers turning localization on for a project, its languages, the string tables its strings are kept in, the Localization window that edits them, plural forms and arguments, reading strings in code, and which language a game starts in.
Localization is off until a project turns it on. A project that never does has no settings file, no tables, and nothing of localization runs.
Images, sounds and fonts with a version for each language are localized assets.
Turn it on
Open Edit ▸ Project Settings ▸ Localization and tick Localize this game. The project gets settings/localization.json, and English as its first language.
| Setting | What it does |
|---|---|
| Languages | The game's languages, in the order a language menu lists them. Drag one to move it. Its menu has Make Default and Remove. |
| Add Language | Picks one of the languages the engine knows, searched by its English name, its own name or its code. A code it does not know, typed, is added by its code. |
| Default | The language the game is written in, marked with a star: what every other falls back to, and what the game starts in when nothing else says. |
| Saved choice first | A game starts in the language its player chose last, where they chose one. |
| Then the system's | Else in the language the system is set to, where the game has it or one of the same language, before the default. |
| Missing strings | What a string the player's language does not have shows: Fall back to the same string in another language, or Show their names, which shows a translation's gaps as the game plays. |
| Notes for Translators | Shows a Note column in the Localization window, a note on each entry for translators, exported with the spreadsheets. Off unless your project turns it on. A note never goes into a build. |
A language is named by its code, as BCP 47 writes it: a language (en, ru), and where needed a script (zh-Hans) or a region (pt-BR, es-419). Unticking Localize this game keeps the languages for later.
String tables
A game's strings are kept in string tables, .strings files anywhere in its assets. Make one with the Project panel's Create ▸ String Table. Each table holds every language: an entry for each string, with its text in each of the game's languages.
Each entry has a name, which code uses, and an identity the table gives it when it is made and never gives another, even after it is deleted. Renaming an entry keeps its identity, so nothing that uses it breaks.
A table is JSON, easy to read and to edit by hand:
{
"abyssStrings": 1,
"nextId": 5,
"entries": {
"Play": { "id": 1, "text": { "en": "Play", "ru": "Играть" } },
"Coins": {
"id": 4,
"plural": "count",
"text": {
"en": { "one": "{count} coin", "other": "{count} coins" },
"ru": { "one": "{count} монета", "few": "{count} монеты", "many": "{count} монет", "other": "{count} монеты" }
}
}
}
}Arguments
A string can name arguments in braces: Score: {score}. Code gives each its value as it asks for the string. A name no argument has is left as it is written, so a mistake shows. Write a brace itself twice: {{ and }}.
A number, a date or a length of time is written as the language writes it, and a place can ask for a style: {price:0.00}, {day:date long}, {left:timer}; see Numbers, dates and right-to-left.
Plural forms
A string with a count, such as "5 coins", needs other words for other numbers, and each language has its own forms. English has two, one and other. Russian has four: 1 монета, 2 монеты, 5 монет, 1,5 монеты. The engine uses the plural rules of Unicode CLDR, and knows each language's forms:
| Form | Used for, in some of the languages that have it |
|---|---|
| zero | Arabic's and Welsh's none; Latvian's 0, 10 and 11 to 19 |
| one | One; in Russian and Ukrainian also 21, 31, and so on |
| two | Two, in Arabic, Hebrew and Welsh |
| few | Russian's and Polish's 2 to 4, Czech's 2 to 4 |
| many | Russian's 5 to 20, Arabic's 11 to 99 |
| other | Everything else; Japanese, Chinese and Korean have only this |
An entry with plural forms has a text for each form of each language, picked by the number one argument holds: count, unless the entry's plural names another. A form a language leaves empty uses its other form. A number is read as it is written, so 1.0 coins is plural in English.
The Localization window
Window ▸ Localization edits the game's string tables. Double-clicking a table in the Project panel opens it there too.
- Tables down the left, each with how many strings its languages are missing. + makes a new table in the Project panel's open folder.
- The sheet on the right: an entry a row, a language a column. A string with plural forms has a row for each form under it. A form a language does not have is shaded, and a missing text is tinted.
- Search finds entries by name or by any text.
- A Note column, each entry's note for translators, such as "Main menu button, 12 letters at most", shows after the names while Project Settings' Notes for Translators is ticked.
- Export and Import write the table as a spreadsheet for translators and read one back; see Spreadsheets for translators.
- + Entry adds one at the end, its name ready to type.
- A cell is typed into where it is, and kept when you click away or press Enter. Each edit is one step of Edit ▸ Undo.
- An entry's menu has Rename (or double-click its name), Copy Code (
Strings.Menu.Play), Make Plural or Make Plain, and Delete (or the Delete key).
The editor writes in Latin, Greek and Cyrillic, and draws Arabic, Hebrew, Persian, Thai, Lao, Armenian, Georgian and Amharic with the Noto Sans fonts it comes with. Chinese, Japanese and Korean are drawn with your system's own fonts. Arabic and Hebrew cells show the text as it reads, right to left with Arabic's letters joined; while you type in one, it shows the letters in the order you type them.
Hindi and the other Indic scripts, Sinhala, Burmese and Khmer join their letters in ways the editor can't draw, so their cells show boxes and their languages are named in English. Their strings work in the game, given a font that has them: write them in a spreadsheet and import it.
Spreadsheets for translators
Translators rarely work in a game engine. Export in the Localization window writes the open table as a spreadsheet, or All Tables to a Folder writes every table, each named after its file, such as General.csv. Send it to a translator, or open it in Google Sheets, Excel or a translation service, and Import what comes back.
A spreadsheet has the same layout as the Localization window: a row for each entry, and a column for each language, headed by its code. A string with a count has a row for each plural form, named in the Form column; a cell is left empty where a language does not use that form. The Id column is what Import matches rows by, so a key renamed after export still finds its entry. A Note column is written when notes are shown or the table has any.
| Id | Key | Form | en | ru |
|---|---|---|---|---|
| 1 | Hello | Hello | Привет | |
| 3 | Points | one | {count} point | {count} очко |
| 3 | Points | few | {count} очка | |
| 3 | Points | other | {count} points | {count} очков |
Export's menu sets two things, both kept on your computer:
- Separator: a Comma, as Google Sheets and Excel in English read a
.csv; a Semicolon, as Excel in most of Europe reads one, Russian, German and French included; or a Tab, for a.tsv. Files are UTF-8 with the byte-order mark Excel needs to read letters other than English. - Rows: All, or Missing a Translation, the entries some language has no text for, to send a translator only what is new.
Import reads one spreadsheet or several, each into the table its file is named after, else the table open, whatever separates its cells. Before anything changes, it says what it would do: how many texts change in which languages, and what it leaves out, such as a row that matches no entry or a column for a language the game does not have. A cell with text sets that text, and an empty cell leaves the text as it is, so a spreadsheet with only Russian filled in never clears German. Import never adds or deletes an entry. The whole import is one step of Edit ▸ Undo, however many tables it changes.
Strings in code
The build writes a key for each entry of each table: Strings, then a class named after the table's file, then the entry's name. A mistyped key, or one deleted from its table, is a build error. Hovering over a key shows what it says in the default language.
// Text, in the player's language.Title.Text = world.Localization.Text(Strings.Menu.Play);
// With arguments, picking the plural form by the count.Coins.Text = world.Localization.Format(Strings.Hud.Coins, ("count", coins));Score.Text = world.Localization.Format(Strings.Hud.Score, ("score", score));An argument is a name and a number or a text, ("count", coins). A string none of the languages has shows its name, Hud.Coins.
A system asks its context, context.Localization, which several systems can ask at once:
[AbyssSystem]private static void ShowCoins(ref Wallet wallet, in SystemContext context){ Log.Info(context.Localization.Format(Strings.Hud.Coins, ("count", wallet.Coins)));}Member of world.Localization | What it does |
|---|---|
Enabled | Whether the game is localized |
Languages | The game's languages, each with its Code, EnglishName and NativeName (Русский, Español) |
Default | The language the game is written in |
Language | The language the player uses. Set it to one of Languages to switch every string to it, and keep the choice for the next start. |
Changed | Raised as the language changes, with the new one |
Text(key), Format(key, arguments) | A string in the player's language |
A language menu lists Languages, each in its own name:
foreach (Language language in world.Localization.Languages){ // A button showing language.NativeName, which sets: world.Localization.Language = language;}Or a dropdown of them, given the languages as its options and bound to the one in use; see Dropdowns.
Which string a player sees
A string missing from the player's language is looked for in its shorter code's language, where the game has it (pt-BR to pt), then in the default. With Missing strings set to Show their names, it is looked for in the player's language alone.
Text in a UI document
A text in a UI document is localized where it is. Open the document, pick the element, and press Localize, the translate icon at the right of the Inspector's Text row. It is there while the game is localized.
- Pick the string table.
- Type the entry's name, or pick an entry from the list, which shows those whose name or text has what you type. The name starts as the element's own,
Titlefor an element called Title. - Make Entry makes a new entry of that name, saying the element's text in the default language. Use Entry uses the one the table has.
The element then says the entry in the language the game is in, and switches as the language does, with no code. Its Text row shows what it says in the language the Game panel shows, and a String row under it names the entry, Menu ▸ Title; click it to pick another. Translate the entry in the Localization window. Stop Localizing, in the same popup, gives the element its own words back. One undo takes back both the entry made and the element's string.
The document keeps the element's own words, and shows them while the game is not localized.
In code, Localize does the same for any element, and fills the string's arguments:
Coins.Localize(Strings.Hud.Coins, ("count", coins));Called again with other arguments, it is filled with them. Giving the element text of its own, Coins.Text = "...", stops it being localized, as Coins.Unlocalize() does.
Strings in components
A component of your game's holds a string as a LocalizedString field:
[AbyssComponent]public partial struct Sign{ public LocalizedString Caption;}In the Inspector the field is a slot naming its string, Menu ▸ Play, or None. A click opens the same popup as Localize: pick a table and an entry, or Make Entry for a new one named as you type, to translate in the Localization window. None empties the field. Resting on the slot shows what the string says in the language the Game panel shows.
In code, read it in the player's language, and give it a key:
string caption = context.Localization.Text(sign.Caption);string coins = context.Localization.Format(chest.Label, ("count", chest.Coins));sign.Caption = Strings.Menu.Play;The field holds the table's identity and the entry's, so renaming either breaks nothing. A scene writes the entry's name beside them for whoever reads the file:
"Caption": { "string": "Menu.Play", "table": "0f8a3c2e7b1d4e5f9a6b8c7d6e5f4a3b", "entry": 1 }A list's item, a data asset and a project's settings hold one the same way. A field naming no string is said as nothing, and so is one whose entry no language has.
Playing in the editor and built games
Play starts the game in the language its settings pick, the player's last choice read from the project's cache. While stopped, the editor shows every string in the default language. A string edited in the Localization window during Play shows at once.
To try a language without changing the game's settings, pick it from the language list in the Game panel's top row, after the size the game is drawn at. The list shows only while the game is localized. Game's Choice plays the game as its settings say. A language picked is played in from Play on, and shown while stopped, and no player's choice is saved. While the game plays, the list shows the language in use, including one the game's code switched to, and a pick switches it at once. The pick is your computer's, kept in the project's cache folder.
A built game carries each language's strings apart from the others, and starts in its language as it opens.
Pseudo-localization
Pseudo, at the end of the Game panel's language list, shows the game in pseudo-localization before any translation exists. Every string of the default language is shown accented and about a third longer, in brackets: Settings becomes [Šéţţîñĝš···]. Arguments such as {count} and plural forms stay as they are. It shows you three things:
- Text that does not go through localization stays plain, so it stands out.
- Text cut off by a box too small for it loses its closing bracket.
- A layout is tried with the longer text most languages need.
Pseudo is in the editor only, never in a build, and is kept on your computer as a language picked is.
Strings players download
A string table is an asset, so it can go into an Addressables group like any other: tick Addressable in its Inspector and pick a group, or drag it onto a group in Window ▸ Addressables. A table in a group that ships is in the main pack in every language, as a table that is not addressable is. A table in a group that is an add-on is downloaded, the default language's strings too.
The build splits such a table by language, so a player downloads only their own: dialogs-en.abypack, dialogs-ru.abypack and so on, each an add-on of its own named for its group and language, such as Dialogs (ru). A language that has none of the table's strings gets no pack. If the group also holds scenes, images or other assets, those go into dialogs.abypack as before; a group of tables alone has no pack of its own, and Window ▸ Addressables shows add-on · dialogs-{language}.abypack beside it. A localized asset in the group goes into the same packs, each with the file its language shows.
So a game can ship a small table of the strings it needs first, and download a large one of dialogs:
Language russian = flow.Localization.Language;IReadOnlyList<AddOn> needed = flow.Localization.AddOnsFor(russian); // its strings not on the computerlong size = flow.Packs.SizeToDownload(needed); // for "Download 5 MB?"foreach (AddOn addOn in needed){ await flow.Packs.Download(addOn);}- A language can be picked whether its strings are on the computer or not, and a game starts in its language as always. A string whose add-on is not attached shows what it falls back to, or its name, as Missing strings says. Once the add-on is attached, its strings show by themselves and
Changedis raised. AddOnsForlists the add-ons of a language's strings that are not attached as the game's list names them: a newer build of one is listed too. A group with a pack of its own is listed once that pack is attached, as its strings come with it.- Downloading a group's add-on downloads its strings in the language in use with it, as one download: its
Size,ReceivedandProgressare theirs together.SizeToDownloadof the group counts both. Remove takes its strings in every language with it. - Strings add-ons are hosted, checked, updated and kept as every add-on is (see Downloading add-ons).
Play with the Game panel's Add-ons at To Download leaves out each table's strings in a language until the game downloads that language's add-on, so a download prompt can be tried by pressing Play.
In the Scripting API
- Localization: the game's languages and strings, and the language the player uses.
- Language and PluralCategory: a language, its names and its plural forms.
- StringKey and LocalizedArgument: a string as code names it, and what fills it in.
- UiElement:
LocalizeandUnlocalize, an element's text made a string and its own again. - LocalizedString: a string a component names.
- StringTable and StringEntry: a string table's file.
- LocalizationSettings and MissingStrings: the project's settings.
