Localization

Quarkdown supports string localization out of the box.

The first step is to set the document language via .doclang {locale}. Call this function among the other document metadata functions (such as .docname, .docauthor, etc.).

The locale value can be either a case-insensitive English full name (e.g., English, Italian, French (Canada)) or an IETF BCP 47 language tag (e.g., en, it, fr-CA).

Built-in localization

Quarkdown’s built-in libraries expose localization tables that localize elements such as quote types, numbering captions, and table of contents title.

The currently supported locales are English, Italian, German, French, Chinese, and Japanese.
Contributions to support new locales are welcome:
stdlib
paperlib

Creating your own localized strings

Example 1

Imagine a function .theorem that displays Theorem. before its content. You could define it as follows:

.function {theorem}
    **Theorem.**

.theorem This is my theorem

Theorem. This is my theorem

This works well for your own English document, but what if you are making a library for everyone to use? You would need to support multiple languages. This is where localization tables come in.

The .localization {name} function defines a new localization table associated with a unique name. Its body parameter accepts a particular Markdown list that, in Quarkdown, is called a dictionary.

This localization dictionary exposes key-value pairs for each locale that you intend to support. The locale names follow the same rules as those from .doclang, meaning they can be full names or tags. As long as .doclang is set, you can access the localized string via .localize {table:key}, in this case .localize {mylib:theorem}.

Example 2

The previous function would now look like this:

.localization name:{mylib}
    - English
      - theorem: Theorem
    - Italian
      - theorem: Teorema

.function {theorem}
    **.localize {mylib:theorem}.**

.theorem This is my theorem

Theorem. This is my theorem

Extending a built-in localization table

If your locale is not yet supported by Quarkdown and you are unable to contribute to the project, you can still extend the built-in localization tables for your document.

When calling .localization {name}, an additional merge:{yes} argument causes the localization table with the given name to be extended with the new user-provided one. Any conflicting entries will be replaced by the new ones.

For instance, typed boxes feature a localized title by default, such as Warning for a warning-typed box. If the document locale is not supported, the title will be missing. To extend the built-in localization with box titles in Canadian French, use the following approach:

.localization {std} merge:{yes}
    - fr-CA
      - warning: Avertissement
      - error: Erreur
      ...

After that, assuming Canadian French is set in .doclang, the new entries will be available to the .box function.

Built-in table names and entries are listed in this page’s Built-in localization.

On this page

Localization

Built-in localization

Creating your own localized strings

Extending a built-in localization table