fs-translation

Type-safe reactive i18n service with multi-locale support.

npm install @script-development/fs-translation

Peer dependencies: vue ^3.5.0

What It Does

fs-translation provides internationalization with two guarantees you don't get from most i18n libraries:

1. Compile-time key validation — misspelled translation keys are caught by TypeScript, not by users
2. Reactive locale switching — changing the locale updates all translated text automatically via Vue's reactivity system

Basic Usage

Define Your Translations

Translations are organized as a two-level nested object: sections containing keys:

const translations = {
  en: {
    common: {
      save: "Save",
      cancel: "Cancel",
      delete: "Delete",
    },
    users: {
      title: "Users",
      empty: "No users found",
      created: "User {name} created",
    },
  },
  nl: {
    common: {
      save: "Opslaan",
      cancel: "Annuleren",
      delete: "Verwijderen",
    },
    users: {
      title: "Gebruikers",
      empty: "Geen gebruikers gevonden",
      created: "Gebruiker {name} aangemaakt",
    },
  },
};

Create the Service

import { createTranslationService } from "@script-development/fs-translation";

const translation = createTranslationService(translations, "en");

Use in Components

<script setup lang="ts">
import { translation } from "@/services";
</script>

<template>
  <h1>{{ translation.t("users.title").value }}</h1>
  <p v-if="!users.length">{{ translation.t("users.empty").value }}</p>
  <button>{{ translation.t("common.save").value }}</button>
</template>

Type-Safe Keys

Translation keys are validated at compile time using TypeScript's template literal types. The t() function only accepts keys that exist in your translation schema:

translation.t("common.save"); // compiles — "common.save" exists
translation.t("common.delete"); // compiles — "common.delete" exists
translation.t("common.submit"); // compile error — "common.submit" doesn't exist
translation.t("invalid.key"); // compile error — "invalid" section doesn't exist

Keys use dot notation: "section.key". This catches typos before your code ever runs.

Parameter Interpolation

Use {param} placeholders in translation strings and pass values at call time:

// Translation: "User {name} created"
const message = translation.t("users.created", { name: "Alice" });
// Result: "User Alice created"

<template>
  <p>{{ translation.t("users.created", { name: userName }).value }}</p>
</template>

Switching Locales

The locale property is a reactive Ref. Assign to it to switch languages — all t() results update automatically:

translation.locale.value = "nl";
// Every ComputedRef from t() now returns Dutch translations

<script setup lang="ts">
import { translation } from "@/services";
</script>

<template>
  <select v-model="translation.locale.value">
    <option value="en">English</option>
    <option value="nl">Nederlands</option>
  </select>

  <!-- Updates automatically when locale changes -->
  <h1>{{ translation.t("users.title").value }}</h1>
</template>

Why is t() a ComputedRef?

Because it needs to update reactively when the locale changes. If t() returned a plain string, you'd have to re-call it every time the locale changes. By returning a ComputedRef, Vue's reactivity system handles it — the template re-renders automatically.

Memoization

The service caches ComputedRef instances by key and params combination. Calling t("common.save") in 10 different components returns the same ComputedRef instance — no duplicate work.

API Reference

createTranslationService(translations, defaultLocale)

Parameter	Type	Description
translations	Record<TLocale, TSchema>	Translation data per locale
defaultLocale	TLocale	The initial active locale

Service Properties

Property	Type	Description
t(key, params?)	(key, params?) => ComputedRef<string>	Translate a key with optional params
locale	Ref<TLocale>	Current locale — assign to switch languages

Translation Schema

Translations must be a two-level nested object:

{
  section: {
    key: "Translation string with optional {param} placeholders";
  }
}

Section names and key names must not contain dots (the dot is the separator in t("section.key")).