Type-safe variables

Type Safety with Variables

typed-locale provides type safety for these variables. When you use a translation that includes variables, TypeScript will ensure that you provide all the necessary variables and that they are of the correct type.

Here's how you would use these translations:

import {createTranslator} from 'typed-locale';

const translator = createTranslator(en);

const greeting = translator(t => t.hello);
console.log(greeting); // Output: 'Hello'

const nameGreeting = translator(t => t.helloName({name: 'Alice'}));
console.log(nameGreeting); // Output: 'Hello, Alice'

const userInfo = translator(t => t.userAge({name: 'Bob', age: 30}));
console.log(userInfo); // Output: 'Bob is 30 years old'

Type Checking

The type system will catch errors if you try to use a translation incorrectly:

// This will cause a TypeScript error because 'name' is missing
translator(t => t.helloName());

// This will cause a TypeScript error because 'age' is not expected
translator(t => t.helloName({name: 'Charlie', age: 25}));

// This will cause a TypeScript error because 'age' should be a number
translator(t => t.userAge({name: 'David', age: '35'}));

Benefits of Type-Safe Variables

Catch Errors Early: TypeScript will catch variable-related errors at compile-time, preventing runtime errors.
Improved Developer Experience: You get autocomplete suggestions for the required variables.
Refactoring Support: If you change a variable name in your translations, TypeScript will help you find and update all usages.
Documentation: The types serve as inline documentation, showing exactly what variables each translation expects.

Advanced Usage: Nested Objects and Arrays

typed-locale also supports more complex structures, including nested objects and arrays. The type system will correctly infer and enforce the structure of these more complex translations.

For example:

export const en = {
  user: {
    profile: {
      greeting: 'Welcome back, {{name}}!',
      stats: 'You have {{postCount}} posts and {{followerCount}} followers',
    },
    preferences: {
      theme: 'Your current theme is {{theme}}',
    },
  },
  listItems: 'Your items are: {{items}}',
} as const;

const translator = createTranslator(en);

const profileGreeting = translator(t => t.user.profile.greeting({name: 'Eve'}));
console.log(profileGreeting); // Output: 'Welcome back, Eve!'

const userStats = translator(t => t.user.profile.stats({postCount: 10, followerCount: 100}));
console.log(userStats); // Output: 'You have 10 posts and 100 followers'

const userTheme = translator(t => t.user.preferences.theme({theme: 'dark'}));
console.log(userTheme); // Output: 'Your current theme is dark'

const itemList = translator(t => t.listItems({items: ['apple', 'banana', 'orange'].join(', ')}));
console.log(itemList); // Output: 'Your items are: apple, banana, orange'

By leveraging TypeScript's type system, typed-locale provides a robust and type-safe way to handle variables in your translations, making your internationalization efforts more reliable and maintainable.