Manual

Manual

Localized images, sounds and fonts

Some assets need a version for each language: a picture with words painted on it, a voice-over, a font with the letters a language needs. A localized asset is a .localized file that names a default file and a file for each language that has its own. Anything that uses an image, a sound or a font can use a localized asset instead, and shows the file of the language the player uses, switching as soon as the language changes.

Only images, sounds and fonts can be localized. A localized asset works whether or not the game is localized: with no languages, it shows its default.

Make one

Right-click an image, a sound or a font in the Project panel and choose Create Localized Asset. A file named like the original, flag.localized, is made beside it, with flag.png as its default, and is picked. A localized asset is drawn as a globe in the Project panel and in the slots that hold one.

If anything uses flag.png already, the editor asks:

flag.png is used in 4 places: Main.scene, Shop.prefab, menu.ui, Flag.mat

  • Use flag.localized There changes every use of flag.png to the localized asset, as one step you can undo: the scenes open in the editor, the scenes, prefabs, UI documents, materials, animation clips and data assets of the project, and a stylesheet's images and its @font-face fonts. A localized asset's own file is left as it is.
  • Only Create It, or Escape, changes nothing. Use it when only one or two things should use the localized asset, and give it to them yourself.

Code that loads the image by its key, Addresses.Ui.Flag, is not changed: change it to the localized asset's key, Addresses.Ui.FlagLocalized, by hand.

Its files

Pick the localized asset to see its files in the Inspector:

RowWhat it is
DefaultWhat every language with no file of its own shows, the default language too.
LanguagesA row for each of the game's languages but the default. Drop a file on a row, or pick one with its button. None shows what the language falls back to.
Find by NameFills each empty row from the files named after the default and the language's code: flag-ru.png, flag.ru.png, flag_ru.png, or ru/flag.png beside it. A file of the default's extension is preferred.

Every file must be the default's kind: a localized image takes only images, a localized sound only sounds. A language the file names that the game no longer has is shown in amber, so you can empty it.

A language with no file of its own falls back as a string does: pt-BR shows pt's file if there is one, else the default.

Using one

A localized asset goes wherever its default's kind does:

  • Images: a Sprite's Image, a UI image, a material's texture slots, a stylesheet's url(), as in background-image: url("/ui/flag.localized");, and world.LoadImage("ui/flag.localized").
  • Sounds: an Audio Source's Clip, and world.LoadAudio("voices/intro.localized").
  • Fonts: a stylesheet's @font-face, with one localized font for each font the game uses, such as a title font and a body font:
@font-face { font-family: "Body"; src: url("/fonts/Body.localized"); }
.text { font-family: "Body"; }

An addressable localized image or sound has a key of its default's kind, an ImageAddress or an AudioAddress, named like the file. Where the file it was made of is addressable too, that file keeps its key, Addresses.Ui.Flag, and the localized asset gets Addresses.Ui.FlagLocalized. A localized font has no key, as fonts are named only by stylesheets.

When the language changes, everything that uses a localized asset changes with it: sprites, UI images, materials, and every text in a localized font, laid out again. A sound already playing finishes in the language it started in; the next one plays in the new language.

Fallback fonts, where letters missing from a font are taken from another, are not part of the engine yet.

The file

A localized asset is JSON, like a material file, and names each file by its path and its identity, so a file moved or renamed is still found:

{
  "abyssLocalized": 1,
  "default": "ui/flag.png",
  "languages": {
    "ru": "ui/flag-ru.png"
  },
  "ids": {
    "default": "3c1d6a0e9b2f4c7d8e5a1b0c9d8e7f60",
    "ru": "4d2e7b1f0c3a4d8e9f6b2c1d0e9f8a71"
  }
}

In a build

A localized asset is packed where it is reached, as any asset is, with every file it shows.

A localized asset in an Addressables group that is an add-on is split by language, as the group's string tables are. Each language's pack, such as voices-ru.abypack, holds the localized asset and the file that language shows: its own, the one it falls back to, or the default. A Russian player downloads only the Russian voice-overs. A group of string tables and localized assets alone has no pack of its own.

The build says where a localized asset names a file the project does not have, or a language the game does not have.

In the editor

The Scene and Game panels show localized assets in the language picked in the Game panel's language list, as they show strings. Pseudo shows their defaults.

In the Scripting API