okp-i18n · ·

OKP i18n is a lightweight internationalization solution specifically designed for Vite-based projects with multilingual support.

Features

1. Translation Management

   • JSON-based translation files
   • Configurable default and supported languages
   • Dynamic translation file loading
   • Automatic fallback when translations missing

2. Translation Functions

   • Simple t() function for translations
   • Support for pluralization using Intl.PluralRules
   • Language-specific translation via getTranslation()
   • Fallback to key when translation missing

3. Development Tools

   • Command-line translation checker
   • Missing translation detection in source files
   • Support for multiple file types (.astro, .jsx, .tsx, .vue)
   • Console warnings for missing translations

Installation

npm i @mcpronovost/okp-i18n

Configuration

Default Configuration

{
  defaultLang: "en",
  currentLang: "en",
  supportedLangs: ["en"],
  useUrlLang: true,
  localesPath: "/src/locales",
}

Direct Configuration

import { initI18n } from "@mcpronovost/okp-i18n";

await initI18n({
  defaultLang: "fr",
  supportedLangs: ["en", "fr"],
  localesPath: "/src/services/locales",
});

Key Components

Translation Files

• Format: JSON files in locales directory
• Supports translations from multiple files
• Supports pluralization rules (one, zero, other)
• Automatic fallback to "other" form

{
  "Hello": "Bonjour",
  "Threads": {
    "one": "Sujet",
    "zero": "Sujet",
    "other": "Sujets"
  },
  "Message": {
    "one": "Message",
    "other": "Messages"
  },
  "User": "Utilisateur"
}

Translation Function

• Simple t() function for accessing translations
• Support for pluralization via count parameter
• Language-specific translations via getTranslation()
• Automatic fallback to key when translation missing

Translation Checker

• Command-line utility for finding missing translations
• Configurable via command line arguments:
  • --languages: Supported language codes (default: ["en"])
  • --locales: Path to locales directory (default: "./locales")
  • --src: Path to source files (default: "./src")
  • --extensions: File extensions to scan (default: [".astro", ".jsx", ".tsx", ".vue"])
• Scans source files for t() function calls
• Reports missing translations with easy to read console output

Direct Command

npx okp-i18n check --languages=en,fr --src=./src --locales=./src/locales

Script in package.json

  {
    "scripts": {
      "dev": "vite",
      "build": "vite build",
      "preview": "vite build && vite preview",
      "lint": "eslint .",
      "check-translations": "check-translations --languages=en,fr --src=./src --locales=./src/_services/locales"
    }
  }

Example Usage

Use default language for translations

import { useEffect } from "react";
import { t, initI18n } from "@mcpronovost/okp-i18n";

// Initialize i18n
await initI18n({
  defaultLang: "en",
  supportedLangs: ["en", "fr"],
  localesPath: "/src/locales"
});

// Use translations
function Home() {
  return (
    <div>
      <h1>{t("Welcome")}</h1>
      <p>{t("Welcome to the home page")}</p>
    </div>
  );
}

Use specific language for translations

import { useEffect } from "react";
import { getTranslation, initI18n } from "@mcpronovost/okp-i18n";

// Initialize i18n
await initI18n({
  defaultLang: "en",
  supportedLangs: ["en", "fr"],
  localesPath: "/src/locales"
});

// Use specific language translations
function Home() {
  const { t } = getTranslation("fr");
  return (
    <div>
      <h1>{t("Welcome")}</h1>
      <p>{t("Welcome to the home page")}</p>
    </div>
  );
}

Peer Dependencies

• Vite (version 6 or higher)

License

This project is licensed under the BSD-3-Clause License.