nile-library - Library supporting nile

This repository contains the library that supports OpenTTD's translation tool nile.

This library for example validates if a translation is valid for a given base-string, and converts base-strings into a translatable form.

Installation

Have Rust installed.

Development

For easy local development:

• Validate base string:

  cargo run -- <base>

• Validate translation string:

  cargo run -- <base> <translation>

It will output the normalized string form, and whether the string is valid; and if not, what was wrong with it.

WASM integration

This tool also integrates with WASM, so validation can be done from any website. For this wasm-pack is used.

wasm-pack build --release

API usage

Step 1: Validate and normalize the base string

API method:

fn validate_base(config: LanguageConfig, base: String) -> ValidationResult

Input:

• config.dialect: One of openttd, newgrf, game-script.
• config.cases: Empty for base language.
• config.genders: Empty for base language.
• config.plural_count: 2 for base language.
• base: Base string to validate

Output:

• errors: List of errors. If this is not empty, the string should not be offered to translators.
• normalized: The normalized text to display to translators.
  • In the normalized text, string commands like RAW_STRING, STRING5, ... are replaced with STRING.
  • Translators can copy the normalized text as template for their translation.

Example:

>>> cargo run "{BLACK}Age: {LTBLUE}{STRING2}{BLACK}   Running Cost: {LTBLUE}{CURRENCY}/year"
ERROR at position 61 to 71: Unknown string command '{CURRENCY}'.

>>> cargo run "{BLACK}Age: {LTBLUE}{STRING2}{BLACK}   Running Cost: {LTBLUE}{CURRENCY_LONG}/year"
NORMALIZED:{BLACK}Age: {LTBLUE}{0:STRING}{BLACK}   Running Cost: {LTBLUE}{1:CURRENCY_LONG}/year

Step 2: Translators translates strings

• Translators must provide a text for the default case.
• Other cases are optional.
• Game-scripts do not support cases. There is a method in LanguageConfig to test for this, but it is not exported yet.

Step 3: Validate and normalize the translation string

API method:

fn validate_translation(config: LanguageConfig, base: String, case: String, translation: String) -> ValidationResult

Input:

• config.dialect: One of openttd, newgrf, game-script.
• config.cases: case from nile-config.
• config.genders: gender from nile-config.
• config.plural_count: Number of plural forms from nile-config.
• base: Base string the translation is for.
• case: Case for the translation. Use "default" for the default case.
• translation: The text entered by the translator.

Output:

• errors: List of errors.
  • severity: Severity of the error.
    • error: The translation is broken, and must not be committed to OpenTTD.
    • warning: The translation is okay to commit, but translators should fix it anyway. This is used for new validations, which Eints did not do. So there are potentially lots of existing translations in violation.
  • position: Byte position in input string. None, if general message without location.
  • message: Error message.
  • suggestion: Some extended message with hints.
• normalized: The normalized text to committed. In the normalized text, trailing whitespace and other junk has been removed.

Example:

>>> cargo run "{BLACK}Age: {LTBLUE}{STRING2}{BLACK}   Running Cost: {LTBLUE}{CURRENCY_LONG}/year" "{BLUE}Alter: {LTBLUE}{STRING}{BLACK} Betriebskosten: {LTBLUE}{0:CURRENCY_LONG}/Jahr"
ERROR at position 61 to 78: Duplicate parameter '{0:CURRENCY_LONG}'.
ERROR at position 61 to 78: Expected '{0:STRING2}', found '{CURRENCY_LONG}'.
ERROR: String command '{1:CURRENCY_LONG}' is missing.
WARNING: String command '{BLUE}' is unexpected. HINT: Remove this command.

>>> cargo run "{BLACK}Age: {LTBLUE}{STRING2}{BLACK}   Running Cost: {LTBLUE}{CURRENCY_LONG}/year" "{BLACK}Alter: {LTBLUE}{STRING}{BLACK} Betriebskosten: {LTBLUE}{CURRENCY_LONG}/Jahr"
NORMALIZED:{BLACK}Alter: {LTBLUE}{0:STRING}{BLACK} Betriebskosten: {LTBLUE}{1:CURRENCY_LONG}/Jahr