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;
};

Fonts

Starting in version 0.52, PostalPoint includes two fonts with very broad character/glyph support; all Latin-based languages, as well as Chinese, Japanese, Korean, and Vietnamese.

These fonts are based on the Noto and/or Roboto font families.

  • PostalPointSans
  • PostalPointMono

It's recommended to use these fonts in your CSS for consistent UIs with good language support.

While not recommended, if needed, the fonts are in TTF format and can be loaded directly with the following paths (relative to the PostalPoint installation):

  • ./assets/fonts/postalpoint-sans/PostalPointSans-Regular.ttf
  • ./assets/fonts/postalpoint-mono/PostalPointMono-Regular.ttf

Medium and bold weight variants of the Sans font are available, but don't have full character coverage; when used in CSS, the fallback is automatic, but keep it in mind if using the TTFs directly.