Skip to content

Localization

Jump to bottom
Daniel Weck edited this page Jul 31, 2019 · 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
  • French
  • Spanish
  • Portuguese (Brazil)

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 generate in its validation report (e.g. rule descriptions, violations, etc.).

The currently-supported languages are:

  • English
  • French
  • German
  • Dutch
  • Japanese

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)
  • (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

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