Skip to content

Latest commit

 

History

History
59 lines (41 loc) · 5.41 KB

definitions.md

File metadata and controls

59 lines (41 loc) · 5.41 KB
Raw

This document gives the definitions and their specifics for the concepts used by this library.

The dictionary

The dictionary is created when loading the default language from a text file, or when loading a compiled dictionary file.

The dictionary contains the namespaces and translation IDs and their respective indexes (TransIndex).

All languages use the same dictionary. If the dictionary is changed, all languages must be regenerated.

Loading non-default languages or a compiled translation file requires that a dictionary already be loaded.

Namespaces

  • Namespaces help keep translation sections separated to help reduce clutter when importing translations into Go.
  • They also allow for duplicate translation IDs per namespace.
  • Namespaces can only contain alphanumeric and underscore characters. Their first character cannot be a number.

Translation IDs

  • These are defined in the translation text files as the property keys directly under a namespace.
  • Translation IDs are used to access translations in 2 ways:
    1. They can be used as strings with a Namespace in the Named: [Must]Get[Plural]Named() functions.
    2. They can be used as indexes from a Generated Go dictionary file in the Indexed: [Must]Get[Plural]() functions. Examples:
      Language.GetPlural(NameSpaceExample.BorrowedNumberOfBooks, 5)
      Language.Get(NameSpaceExample.WelcomeTitle, "Dakusan", time.Now(), currency.GBP.Amount(1275.98), 1492)
  • There cannot be conflicting IDs in a single Namespace.
  • Translation IDs must start with an uppercase alphabetic character. Afterward they can contain unicode letters, unicode digits, or underscores.

Translation strings

Fallback languages

Each language can contain 1 optional fallback language, set as a language identifier in its settings section via Settings.FallbackLanguage.

If a translation was not defined for a language, then its fallback language will be checked.

Fallback languages are checked recursively up to the default language.

When manually loading language files, Language.SetFallback() must be used. Fallback languages must use the exact same dictionary.

The default language

The default language (global_settings.DefaultLanguage) must contain all the translation IDs. The internals of this module (the dictionary) are formulated through the default language.

If a translation ID is missing from a non-default language, and it does not have a fallback language, then the translation from the default language is returned.

The default language does not have a fallback language.

Compiled binary translation files

One file per language is placed in global_settings.CompiledOutputPath. They are named $LanguageName.gtr and have a .gz (gzip compress) suffix added if global_settings.CompressCompiled is turned on.

A special dictionary file containing the translation IDs and namespaces is compiled from the dictionary and uses its ordering. It is saved as dictionary.gtr. When the dictionary is updated, all other translation files may need to be updated. A variables dictionary is also saved to variables.gtr, but it is only ever used when processing non-default language translation text files and the compiled dictionary is being loaded.

Language identifiers

The language identifier identifies the i18n locale for formatting dates, currencies, etc. They are the two-letter ISO 639-1 language code with an optional dash and a ISO-3166 country code. The full list can be found here.

When using the command line interface or the automated library functions:

  • The filenames (without the extension) must match the language identifiers
  • Language identifiers are used to identify and link fallback languages.