I18n Plugin

A staticbolt plugin that adds internationalization to your project. At build time it copies every HTML page once per configured locale, replaces translation keys with their values, and gives you compile-time helper functions for JavaScript and TypeScript. The default locale is served from the root path. Every other locale sits under its own directory prefix.

Installation

The plugin ships as part of @staticbolt/core. You do not need to install anything else.

Usage

In your .staticbolt.ts configuration file:

import { defineConfig } from "@staticbolt/core";
import { i18nPlugin } from "@staticbolt/core/plugins";

export default defineConfig({
  plugins: [
    i18nPlugin({
      defaultLocale: "en",
      supportedLocales: ["en", "ar"],
      localesDirectory: "./sources/locales",
    }),
  ],
});

Translation files

Create one JSON file per locale inside the localesDirectory. All locale files must share the same key structure.

sources/
└── locales/
    ├── en.json
    └── ar.json

Keys can be nested as objects. Values support placeholders written as {{ name=defaultValue }}, where =defaultValue is optional.

{
  "header": {
    "title": "My page title",
    "subtitle": "Page {{ pageNumber=0 }}"
  }
}

{
  "header": {
    "title": "عنوان الصفحة",
    "subtitle": "{{ pageNumber=0 }} عنوان الصفحة الفرعي"
  }
}

Usage in HTML

Text content

Add the i18n attribute to any element with a dot-notated key path. The plugin sets the element's text content to the translation for each locale.

<h1 i18n="header.title"></h1>

<!-- en output -->
<h1>My page title</h1>

<!-- ar output -->
<h1>عنوان الصفحة</h1>

Attributes

Use i18n-attr-* to translate an attribute value, where * is the attribute name.

<img i18n-attr-alt="header.title" src="./logo.png" />

<!-- en output -->
<img alt="My page title" src="./logo.png" />

Placeholders

Use i18n-placeholder-* to fill in a placeholder defined in the translation value, where * is the placeholder name. Placeholder replacement also applies to i18n-attr-*.

<p i18n="header.subtitle" i18n-placeholder-pageNumber="5"></p>

<!-- en output -->
<p>Page 5</p>

<!-- ar output -->
<p>5 عنوان الصفحة الفرعي</p>

You can also reference another translation key as a placeholder value by prefixing it with @.

<p i18n="header.subtitle" i18n-placeholder-pageNumber="@header.title"></p>

To use a literal @ character in a placeholder value, escape it with @@.

Usage in JavaScript and TypeScript

The following functions are resolved at compile time and replaced with their output values. All arguments must be static strings or objects. Dynamic values are not supported.

You can read the current locale at runtime from the lang attribute on the root element.

// Runtime — dynamic
const currentLocale = document.documentElement.lang as I18nLang;

// Compile-time — replaced with their values at build time

/** Replace a placeholder in a string. */
i18n_fill_template("Hello {{ name }}", { name: "world" });
// → "Hello world"

/** Get all supported locales. */
i18n_locales();
// → ["en", "ar"]

/** Get the default locale. */
i18n_default_locale();
// → "en"

/** Get the translation value for a key in a specific locale. */
i18n_key_value("header.title", "en");
// → "My page title"

// Optionally pass placeholder values
i18n_key_value("header.subtitle", "en", { pageNumber: "2" });
// → "Page 2"

/** Get the translation for a key across all locales. */
i18n_key_values("header.title");
// → { en: "My page title", ar: "عنوان الصفحة" }

/** Get all translations for a specific locale. */
i18n_lang_values("en");
// → { header: { title: "My page title", ... } }

/** Get all translations for all locales. */
i18n_all();
// → { en: { header: { ... } }, ar: { header: { ... } } }

Autocompletion

This CLI command generates an HTML custom data file and a TypeScript declaration file for editor autocompletion.

staticbolt locales

This writes two files inside the localesDirectory:

• i18n.html-data.json provides HTML attribute and value autocompletion in editors that support custom HTML data.
• i18n.types.d.ts provides TypeScript types for I18nLang, I18nKeysPath, and all compile-time functions.

To enable HTML autocompletion in VS Code, add the following to .vscode/settings.json:

{
  "html.customData": ["./sources/locales/i18n.html-data.json"]
}

Plugin Options

defaultLocale

• Type: string
• Default: "en"

The default locale. Pages for this locale are served from the root path without a locale prefix.

supportedLocales

• Type: string[]
• Default: ["en"]

All locales the plugin should generate pages for. Each value must match a JSON file in the localesDirectory.

localesDirectory

• Type: string
• Default: "./sources/locales"

Path to the directory that holds the locale JSON files, relative to the project root.

i18nAttribute

• Type: string
• Default: "i18n"

The attribute that sets an element's text content to a translation value.

i18nAttributePrefix

• Type: string
• Default: "i18n-attr-"

The prefix for attributes that translate another attribute's value.

placeholderPrefix

• Type: string
• Default: "i18n-placeholder-"

The prefix for attributes that supply placeholder values to a translation string.