Skip to content

Localization

Jump to bottom
Daniel Weck edited this page Jul 15, 2023 · 13 revisions

Ace Localization

Ace is a command line tool (aka "CLI") that does not expose a Graphical User Interface. However, Ace does in fact generate an HTML report in order to create a human-friendly presentation of the validation information. This is effectively a "user interface" that needs to be translated as part of Ace's global localization effort. Furthermore, Ace implements additional checking rules (see Axe section below about the "base" underlying rules) that output translated labels.

The Ace CLI is made with several individual components (i.e. building blocks) which are ; technically-speaking ; independent NPM packages. There are 3 Ace-related packages which contain localization resources:

  • ace-core
  • ace-report-axe
  • ace-report

The currently-supported languages are:

  • English (credits @marisademeglio @rdeltour @danielweck)
  • French (credits @danielweck @rdeltour)
  • Spanish (credits @nvdaes)
  • Portuguese-Brazil (credits @thiagoeec)
  • Danish (credits @ddfreiling @MyDK)
  • Japanese (credits @murata2makoto @shunito)
  • German (credits ?)

Axe Localization

Ace relies on the Axe library to execute (most) tests inside the individual HTML documents of EPUB publications. Axe implements its own localization strategy and techniques, in order to provide translations of the messages it generates in its validation report (e.g. rule descriptions, violations, etc.).

The currently-supported languages are:

  • English
  • French
  • German
  • Dutch
  • Japanese
  • Danish
  • Portuguese (Brazil)
  • Spanish

See the Axe "readme":

https://github.com/dequelabs/axe-core/blob/develop/README.md#localization

(note that English is "baked in", other languages are externally-defined in JSON files)

https://github.com/dequelabs/axe-core/tree/develop/locales

Choosing a Language at Runtime

The Ace CLI (Command Line Interface) takes configuration parameters. The --lang parameter (or its -l shorter version) is used to specify the language, currently either of:

  • en (English)
  • fr (French)
  • da (Danish)
  • es (Spanish)
  • ja (Japanese)
  • de (German)
  • pt_BR (Portuguese, Brazil)
  • (other language codes are ignored, fallback to English)

English is the default language, in the sense that it is used as a fallback any time a label is not translated in another language (i.e. not specified in the corresponding JSON resource).

Ace CLI lang parameter:

https://github.com/daisy/ace/blob/4c6f5627ffdf14190342a3854d49b82df28aee49/packages/ace-cli/src/index.js#L37

Note that there is another CLI to launch the HTTP service (same command line parameters):

https://github.com/daisy/ace/blob/4c6f5627ffdf14190342a3854d49b82df28aee49/packages/ace-http/src/index.js#L44

Updating Existing Localization Resources / Contributing New Languages

In both cases, GitHub Pull Requests must be created in order to propose edits to the JSON resources that contain the translated labels. The Ace locales for each sub-package are:

...please, also update the name of the language itself in these files:

Note that Axe has its own locales / JSON resources, but the localization process is outside of Ace's control. Pull Requests can be submitted for review in Axe's own GitHub repository. See:

https://github.com/dequelabs/axe-core/tree/develop/locales

Developer Workflow, Tooling

  • yarn i18n-sort: this script ensures that the i18next keys in all locale JSON files (e.g. primary English, as well as secondary French, Spanish, etc.) are sorted in alpha-numerical order. This script also forces consistent JSON formatting (4-spaces indentation, line break at the end of the file). So, this is effectively a normalization step that produces a consistent, (kind of) canonical representation of the l10n resources, which is not only useful for manual processing / comparison between languages, but also a prerequisite for the following scripts.
  • yarn i18n-scan: this script performs a static analysis of the codebase in order to extract all i18next keys used in the software, builds a dummy language resource (temporary JSON file) containing all the hierarchical keys (with empty string values), which is then used as a "master" template to compare against the real JSON locales (e.g. primary English, as well as secondary French, Spanish, etc.). See the following script description to learn more about the outcome of the comparison process.
  • yarn i18n-check: this script compares the primary English locale JSON with the secondary languages. The script removes all unused keys, and adds missing keys (with empty string values). A simple git --no-pager diff can be used to visualize differences. Identifying keys that need translating is simply a matter of searching for empty string values.

Additional Utilities

Under the hood, Ace utilizes the i18next library in order to handle the localization resources at runtime (i.e. JSON files). There are a number of utilities that can ease the process of comparing language keys / values, detecting missing entries, etc.:

https://www.i18next.com/overview/plugins-and-utils

Clone this wiki locally