Local Loader

Loads translation content from the local file system,
supporting multi-file, nested structures and multiple formats.

Local Loader requires access to the local file system.
If your application is deployed as a pure frontend app or on hosted platforms (such as Vercel), use Bundled instead.

Loading Flow

Local Loader starts from the rootDir and collects translation files for the target locale.
It can optionally restrict the loading scope via namespaces,
and then parses and merges the result into LocaleMessages.

Local Loader ─▶ Collect files ─▶ Parse (readers) ─▶ LocaleMessages

Messages Organization


index.json
index.yaml
note.md
index.json
error.json

Each locale corresponds to a dedicated directory
Nested folder structures and multiple files can be created under each locale
Any file format is supported, depending on the readers injected when enabling the Loader

For details on readers and extension mechanisms, see: Readers .

Key Structure Rules

The Loader derives the full key path for each entry based on the folder structure and file names.

Each folder level contributes a segment to the key prefix.

messages/
└─ en/
   ├─ index.json
   │   └─ { text: "Hello" }     → Key: "text"
   └─ ui/
      └─ index.json
          └─ { text: "Hello" }  → Key: "ui.text"

When a file name is not index, the file name itself is treated as a key segment.

messages/
└─ en/
   ├─ index.json
   │   └─ { text: "Hello" }    → Key: "text"
   └─ ui.json
       └─ { text: "Hello" }    → Key: "ui.text"

Usage

Local Loader is enabled via Config .

defineIntorConfig({
  loader: {
    mode: "local",
  },
});

When using Local Loader, locale navigation will trigger a full reload to ensure that translation files for the new locale are loaded correctly.

If a Loader is also provided on the client, locale switching will no longer automatically trigger a full reload.

defineIntorConfig({
  server: {
    loader: {
      mode: "local",
    },
  },
  client: {
    loader: {
      url: "https://public-cdn.com/messages",
    },
  },
});

To force a full reload during locale navigation, enable routing.forceFullReload.

Readers

readers are the extension mechanism for Local Loader,
used to support different file formats and normalize them into MessageObject.

Built-in support for .json
Official reader packages
Custom formats can be supported by implementing additional readers

For the reader interface and implementation details, see: MessageReader

The supported file formats are determined by the readers injected at runtime.
Example injection:


await intor(intorConfig, {
  readers: {
    md: mdReader,
    yaml: yamlReader,
    // ...
  },
});
await getTranslator(intorConfig, {
  readers: {
    md: mdReader,
    yaml: yamlReader,
    // ...
  },
});