lingora

Site | GitHub | API | Coverage Report

lingora is a free and open-source localization management program that analyses fluent translation file for missing or redundant translations. It also supports users of the dioxus-i18n crate.

lingora is designed primarily to be used as a command line tool, but also provides a terminal user interface.

Latest Release Downloads

cli - linux | macos | windows | tui - linux | macos | windows

Install

cargo +nightly install lingora-cli
cargo +nightly install lingora-tui

Terminology

A Canonical locale document is the master against which all other documents are compared.

Primary locale documents are documents in other locales that provide their translations from the Canonical document.

Variant locale documents are documents using the same language root as a Canonical or Primary document, but have different regions.

A “locale” document is formed from multiple files within the fluent sources paths (Lingora.toml or command line argument).

The locale of a fluent file is determined from path naming. If the file name is a locale (e.g. ./i18n/en-GB.ftl, or ./i18n/errors/en-GB.ftl) then that will be deemed the locale of its contents. If the file name is more descriptive (e.g. ./i18n/en/en-GB/errors.ftl), then its locale will be deemed to be the first parent segment which represents a valid locale according to BCP 47. In the example’s case this is en-GB, not en.

Note: A name such as ./i18n/en/en-GB/fr.ftl will be deemed french (fr), which may not be as intended.

Configuration

A Lingora.toml configuraton file is the preferred way to define the locations of the fluent files within the development environment. Each of the settings within the file can be overidden (or provided solely) by command line arguments at runtime.

The Lingora.toml defines:

• The Canonical locale.

• The Primary locales.

• The paths for all fluent files to be analysed. This can be a root folder (e.g. ./i18n/) if all translation files are provided under one location.

If the Lingora.toml file exists in the current working directory then it will be used. An explicit config file can be provided using the --config=path/to/your-config.toml command line argument. If no config file exists then sensible defaults will be used (see default_lingora.toml).

It is recommended that projects provide an explicit Lingora.toml file minimally specifying the Canonical translation file so that all other files are compared against it, rather than the locale of a user’s workstation, which would vary from user to user.

By default (i.e., no toml file exists, or is specified) lingora will look for the translation files in ./i18n/ and it will use <current_system_locale>.ftl as the Canonical translation file.

Command line arguments can be used to override config file settings, with --canonical path/to/canonical_file.ftl and --primary path/to/primary_file.ftl command line arguments. The canonical and primary path names are expected to use the <language>-<locale> or <language>-<script>-<locale> naming convention as described above.

Dioxus

lingora provides additional functionality for users of the dioxus-i18n crate.

• automate creation a Rust source file (config.rs) containing a function to create an I18nConfig struct.

• scan Rust source files for their use of dioxus_i18n::t!, te! and tid! macros, ensuring, if possible, that the translation exists in the canonical file.

Runtime

Lingora comprises two programs:

• a command-line program, intended for quick summarisations of the integrity of the translation and Rust source files.

  lingora-cli --help
  

• a terminal user interface enabling browsing of the translation files and identifiers.

  lingora-tui --help
  

Github action

lingora-cli can be run in GitHub Actions. Example:

jobs:
  i18n:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Run Lingora
        uses: nigeleke/lingora@<version> # E.g. nigeleke/lingora@v0.4.0
        with:
          args: --config=./i18n/Lingora.toml # Optional; none or any cli args can be provided here.
          working-directory: ./i18n # Optional; default "."
          version: v0.4.0 # Optional; default "latest"

Note: the default version (latest) may result in a later version of lingora-cli running than the action version.

Note: the action is executed with a default system locale en_GB.UTF-8; this should not matter the canonical locale should be defined in config settings rather than defaulted.

Developmemt

cargo test
cargo llvm-cov

Build & run

cargo build
cargo run -p lingora-cli
cargo run -p lingora-tui