Software is used by a wide variety of folks who live in a wide variety of regions. As such, both the macOS operating system and Nova support localization into multiple languages. To enable this for its extensions, Nova provides a suite of tools that make it easy to ensure that your extension can be used in multiple languages with minimal effort.

Supported App Languages

Currently, the Nova editor and IDE is localized into the following languages:

Translation Files

Extensions can add localization support for multiple languages by using translation files in JSON-format in special subfolders of the extension.

For each specific language an extension wishes to provide, a folder should be created in the extension root with the following name format: <language_code>.lproj

The language code is one those defined by the IETF BCP 47 standardization. The language codes for those directly supported by the Nova IDE itself are listed in parenthesis above.

By default, any assets and text provided by the extension is assumed to be its “Base” localization. This localization is the fallback used when a more specific localization does not apply. As such, it’s often common to place English translations in this base localization, and to not provide a specific English localization folder.

To provide localizations for the French language, for example, the extension should provide a folder named fr.lproj in its root. This will cause the extension runtime to look in this folder first for string translations if the user is running using a French locale.

Within a localization folder (lproj), an extension may provide one or more JSON files for translated text. The name of the JSON file represents the table name used for localization. The default file name is strings.json, which will be referenced if no table name is provided. Most extensions will likely only need a single strings.json file.

Localizing UI Text

By default, any text that is provided to the Nova IDE through an extension’s extension.json manifest (such as display names for preference keys) will automatically be looked up in the extension’s localization tables without the need to provide localizations through code.

As a general rule of thumb, if text is sent to Nova in your JavaScript code, you should localize it in code (see below). If the text is provided statically using the manifest it will be automatically localized at runtime by Nova.

Localizing Text in Code

To utilize localized text in your extension’s JavaScript code, use the nova.localize() method available on the Environment object. This function takes three arguments: a key, a value, and (optionally) a table name.

The key argument represents the key in the relevant localized JSON file that will be used for lookup. If the user is running in a French locale, it will be looked for in the fr.lproj folder.

The value argument represents the value to return if no suitable localized text can be found. This is a fallback that represents your “base” localization.

The tableName argument represents which JSON file in which to look up the translation (without the .json file extension). If not provided, it will be looked up in a strings.json table as if strings had been provided as the argument.

Because users can configure their system with a cascade of supported languages, Nova will attempt to localize text using the same fallback behavior. If a user configures their system to use French, German, and English (in that order), Nova will look for a translation in the fr.lproj, de.lproj, and en.lproj directories. If none is found, it will fall back to the value argument.