@simplelocalize/typesafe-i18n-connector

Import and export typesafe-i18n translations to/from flat JSON files compatible with SimpleLocalize.

Installation

npm install @simplelocalize/typesafe-i18n-connector

typesafe-i18n (>=5.0.0) is a peer dependency and must be installed in your project.

Usage

Export translations

Reads typesafe-i18n translation files from disk, flattens them into flat key-value JSON files (or keeps the nested structure with flatten: false), and writes them to the output directory.

import { exportTranslations } from '@simplelocalize/typesafe-i18n-connector'

// Use defaults (outputs to ./locales-json/)
await exportTranslations()

Import translations

Reads flat JSON files from the input directory, unflattens them, and stores them as typesafe-i18n translation files on disk.

import { importTranslations } from '@simplelocalize/typesafe-i18n-connector'

// Use defaults (reads from ./locales-json/)
await importTranslations()

Add to package.json

You can paste both codes into scripts/exporter.ts and scripts/importer.ts and and add import + export scripts:

    "scripts": {
        ...
        "i18n:export": "tsx scripts/exporter.ts",
        "i18n:import": "tsx scripts/importer.ts"
    },

To automate the process by simply running npm run i18n:export or npm run i18n:import

File structure

The connector reads and writes flat JSON files organized by locale and namespace:

locales-json/
├── en/
│   ├── base.json        # root translations
│   ├── counter.json     # "counter" namespace
│   └── features.json    # "features" namespace
├── de/
│   ├── base.json
│   ├── counter.json
│   └── features.json
└── ...

Exported files are compatible with the Single Language JSON file format used by SimpleLocalize.

Each JSON file contains flat key-value pairs:

{
  "greeting": "Hello {name}!",
  "welcome": "Welcome to the app."
}

Nested typesafe-i18n keys are flattened with dots:

{
  "section.title": "My Section",
  "section.description": "A description"
}

SimpleLocalize integration

After exporting translations, use the SimpleLocalize CLI to upload and download translations.

See example/simplelocalize.yml for a working configuration. Example simplelocalize.yml:

uploadLanguageKey: en
uploadFormat: single-language-json
uploadPath: ./locales-json/en/{ns}.json
uploadOptions:
  - UPDATE_TRANSLATIONS
  - ACTIVATE_PRESENT_KEYS
  - DEPRECATE_NOT_PRESENT_KEYS
  - MARK_AS_ACCEPTED

downloadFormat: single-language-json
downloadPath: ./locales-json/{lang}/{ns}.json
downloadOptions:
  - EXCLUDE_DEPRECATED_KEYS

Workflow:

# 1. Export typesafe-i18n translations to JSON
npm run i18n:export

# 2. Upload to SimpleLocalize
simplelocalize upload --apiKey YOUR_API_KEY

# 3. Download translations from SimpleLocalize
simplelocalize download --apiKey YOUR_API_KEY

# 4. Import JSON back into typesafe-i18n
npm run i18n:import

Example

The example/ directory contains a full React + Vite app demonstrating the connector with:

• Multiple locales (en, de, fr, es, pt, pl, it)
• Namespace support (counter, features) with on-demand loading
• Language switcher

To run the example:

cd example
npm install
npm run dev

Customization

Export options

You can customize export function like this:

await exportTranslations({
  outputDir: './my-translations',
  defaultNamespace: 'common',
  cleanOutputDir: false,
})

Option	Type	Default	Description
outputDir	string	./locales-json	Directory to write exported JSON files to
cleanOutputDir	boolean	true	Remove output directory before exporting
defaultNamespace	string	base	Filename (without .json) for root-level translations
flatten	boolean	true	Flatten nested keys with dots (e.g. section.title). Set to false to write nested JSON mirroring the source structure

Import options

You can customize import function like this:

await importTranslations({
  inputDir: './my-translations',
  defaultNamespace: 'common',
})

Option	Type	Default	Description
inputDir	string	./locales-json	Directory to read JSON files from
defaultNamespace	string	base	Filename (without .json) for root-level translations
baseLocale	string	en	Locale processed first. Must match your typesafe-i18n base locale — other locales would otherwise have their namespace files silently skipped

License

MIT