Work In Progress
This documentation is in beta. It's missing lots of content, search is broken, and many links go nowhere. These problems will be fixed before release, but there's plenty of work left!
Skip to main content

Concepts

Before getting started, we recommend familiarising yourself with a few terms and types.

Terminology​

As the i18n framework began as a JVM project, it uses terminology generally understood by the Java development community:

  • Resource Bundle: A bundle of files that share a directory, prefix, and file extension, placed within your project's resources and packaged along with it when built.

  • Translation Bundle: A resource bundle containing a set of translations, including a set of base translations in a file matching the last part of the bundle's name, along with a set of files for each language. Languages are defined by appending them to the filename, before the extension — for example. strings.properties would become strings_tok.properties for Toki Pona, or strings_es-AR.properties for Argentinian Spanish.

    In this framework, translation bundles must include a containing folder that is itself placed within translations/ in your project's resources. For example, template.strings refers to translations/template/strings.properties in your project's resources.

The framework also introduces its own terminology:

  • Bundle: Short-hand form of "translation bundle".

  • Key: Translation keys, which are the dotted-form string you use to reference a specific translation in your bundle. For example, if a properties file contains commands.slap.name=slap, then the key is commands.slap.name.

    In this framework, you still use dotted-form strings to represent keys, even if the file format mandates a nested object structure. In situations like that, you use a dot to split the current nesting level from the next one.

  • File Format: Refers to how a file is structured, by referencing its format by name. Some examples include JSON, Properties, TOML, YAML, etc.

  • Message Format: Refers to how individual translations are formatted within a file, by referencing the formatter to be used. Some examples include ICU v1, ICU v2, Fluent, etc.

Platform Types​

We also recommend reading up on how the following platform types work:

  • The Java Locale type is one of the core types you'll need to work with — at least until Kotlin has its own equivalent Locale type.

    This type represents various locales (valid or not), containing languages, scripts, regions, variants, and extensions.