@dialpad/i18n-services contains all the tooling needed to manage the resources for our i18n packages, i.e. @dialpad/i18n-vue2 for legacy apps and @dialpad/i18n for modern apps. this includes:

• Uploading new strings to a translation service.
• Downloading translated strings from a translation service.
• Loading bundled resources at runtime for a given locale.
• Generating a "Dialpadistan" locale from en-US.

There are essentially two main concepts behind the scenes:

The BaseLocaleManager having the common logic that oversees internationalization (i18n) in a Vue2.js and a Vue3.js application using the Fluent localization framework. Its responsibilities include:

• Loading and caching translation bundles: Manages the .ftl data, which maps keys to text for each locale.
• Switching the current locale: Provides methods to change the active language dynamically.
• Handling bundle namespaces: Manages potential duplicate bundle requests from multiple sources, though this feature is still being refined.
• Initializing the Vue plugin: Exposes translation methods ($t, $ta) to Vue templates, enabling localized content within the application.

The second key concept is the BundleSource interface, which abstracts the loading and management of localization resources. This interface has two primary implementations: RawBundleSource and HTTPBundleSource, each designed for different use cases.

• RawBundleSource: This implementation handles localization resources defined within the application. It organizes these resources defined directly in the application, and imported directly at runtime (for example, using import(./[locale].ftl). This approach is ideal for applications with mostly static content.

• HTTPBundleSource: This implementation fetches localization resources dynamically from a server. It caches these resources locally, allowing for efficient access while still being flexible enough to load translations on demand.

Disclaimer: Both implementations are provisional and may change as we better understand our needs. Currently, RawBundleSource is the preferred option for most applications.

If you're looking for the 'Dialpadistan' translator, please skip to this section.

pnpm add @dialpad/i18n-services

You can find the needed configuration for using $t and $ta functions in your application in the i18n for vue2 and i18n for vue3 documentation. In both cases the needed configuration should be the same.

The API for our i18n tools is the same either for the vue3 or vue2 supported versions. You can find the more details about how to use the tool in the i18n for vue2 and i18n for vue3 documentation.

This feature uses the @fluent/syntax parser and a set of regex and grammar rules to convert an en-US.ftl file into an dp-DP.ftl inside the same directory. The "dialpadistani" language is just the original language transformed character-per-character to non-latin characters which is useful to test the proper render of different fonts.

For example:

# src/localization/en-US.ftl

MESSAGE_INPUT_LABEL = New message input
FEED_NEW_SEPARATOR = Beginning of unread items

Will translate to:

# src/localization/dp-DP.ftl

MESSAGE_INPUT_LABEL = Ŋάŵ ɱάššëğά īŋþø†
FEED_NEW_SEPARATOR = Sάğīŋŋīŋğ ůƒ øŋřάëḍ ī†άɱš

To execute a Dialpadistan translation you should run the following script pointing to your Fluent English file: (Note: it can either be a relative path or an absolute path)

pnpm pnpm --filter=@dialpad/i18n-services run translate:dialpadistan /your/english/fluent/file/en-US.ftl

When succeeding translating, you will notice a message on your terminal stating the folder where the output file will be placed. This folder is the same as your English Fluent file.

e.g. in this case you will see File transformed and saved as /your/english/fluent/file/dp-DP.ftl.

This translator includes a post-commit that automatically translates english files to dialpadistani. This hook checks the commit for changed en-US.ftl files and will only run the translator against those files that had changes in the commit.

If this script finally makes any change to dp-DP.ftl files, it will automatically commit those changes with the message: chore(auto-generated): translate en-US.ftl files to dialpadistani

There is one specific scenario where this translator is failing, and we don't consider it to be harmful. This is because of a bug on @fluent/syntax parser.

And this is when having a comment right in the middle between an equal sign and a value, and that comment has at least one placeholder, whatever's after the text of the first placeholder will be translated (and if the comment it's multi-lined every comment line will be squashed and inlined after that placeholder as well)

e.g.

MY_KEY =
    # My awesome comment
    # And here the {$placeholder} is present
        .aria-label = { $name } ({ $muted ->
        [true] Muted{" "}
        *[other] {""}
    })

will be translated to:

MY_KEY =
    # My awesome comment
    # And here the {$placeholder} os sintirp
        .aria-label = { $name } ({ $muted ->
        [true] Muted{" "}
        *[other] {""}
    })

This is because the way@fluent/syntax parser works at the current version. In order to fix this it would require an amount of effort that is probably not worth it. It will imply either to patch the parser behavior somehow or extra usage of regex pre and post processing files, which will not only increase complexity of the solution but also reduce the robustness of it. And given the fact that is just a comment, we prefer not to solve it in-house and wait until they fix or improve this behavior on upcoming versions.

But keep in mind that whenever adding comments, it should be before the whole KEY = VALUE and not in between.

• Fluent docs
• I18n best practices
• i18n for vue2 docs
• i18n for vue3 docs