Skip to content

Internationalization/Translation (i18n)

Starting with v0.51, plugins can access PostalPoint's i18next translation system.

Translation files bundled with your plugin are automatically detected and loaded, assuming you've added a couple lines to your package.json.

Basic Info

i18next can be set up in many different ways. Here's how the instance in PostalPoint is configured.

  • JSON5 file format for translation strings
  • ~~ between the namespace and string key
  • ~ to denote a sub-key
  • Automatic fallback to en language code if no language-specific translation available
  • Missing strings will be written to namespace.missing.json5 if the hidden config setting i18nsavemissing is set to 1.

Setup

In your package.json, add:

"postalpoint": {
    "i18nNamespace": "your-custom-id-here",
    "i18nFiles": ["extrai18nfile"]
}

Then create an i18n folder next to your package.json, with subfolders for language codes (en, fr_CA, es_MX, etc).

Inside each language folder, create a file named your-custom-id-here.json5.

You can add additional translation files (namespaces) for each language by adding them to the i18nFiles array and creating a ${namespace}.json5.

Usage

For strings in the "main" translation file (your-custom-id-here.json5), call t("plugin.your-custom-id-here~~stringKey").

For strings in a file/namespace in the i18nFiles list, call t("plugin.your-custom-id-here.namespace-here~~stringKey").

PostalPoint supports setting a different language for customers; use tc() for customer-facing strings, such as receipt text or the customer display, and the correct language strings will be returned automatically.

Example

This simple, real-world example is from the Custom Web Tools plugin.

i18n/en/customwebtools.json5:

{
    "websiteTitle": "Website {{n}} Title",
    "websiteAddress": "Website {{n}} Address/URL"
}

i18n/fr_CA/customwebtools.json5:

{
    "websiteTitle": "Titre du site Web {{n}}",
    "websiteAddress": "Adresse/URL du site Web {{n}}"
}

package.json:

{
    "name": "postalpoint_custom_web_tools",
    "version": "1.2.0",
    "main": "webtools.js",
    "author": "PostalPortal LLC",
    "license": "BSD-3-Clause",
    "description": "Add websites to the Tools page for instant access without leaving PostalPoint. Supports scanning barcodes into the websites for easy data entry.",
    "postalpoint": {
        "pluginname": "Custom Web Tools",
        "minVersion": "000051",
        "i18nNamespace": "customwebtools",
        "i18nFiles": []
    }
}

From webtools.js:

exports.config = function () {
    let config = [];
    for (var i = 0; i < 5; i++) {
        config.push({
            type: "text",
            key: "app.postalpoint.customwebtools.title" + i,
            defaultVal: "",
            label: t("plugin.customwebtools~~websiteTitle", {n: (i + 1)}),
            placeholder: "",
            text: ""
        });
        config.push({
            type: "text",
            key: "app.postalpoint.customwebtools.url" + i,
            defaultVal: "",
            label: t("plugin.customwebtools~~websiteAddress", {n: (i + 1)}),
            placeholder: "https://example.com",
            text: ""
        });
    }
    return config;
};