Dictionaries

Dictionaries in Vay are foundational to the library's approach to internationalization, providing the mappings between tokens and their phrases in various languages.

Token & Phrases

A dictionary consists of tokens and phrases, where each token can be mapped to a corresponding phrase. A token is a textual representation of the translation path, eg. this.is.a.nested.token, for a deeply nested dictionary. This is similar (but not equal) to the dot notation you would use to access the dictionaries content. A phrase can be either a string, a function returning a string, a object containing numbers as keys and strings as values, or a object containing more phrases. The type for a Phrase looks like this:

export type Phrase =
    | string
    | (ctx: any) => string
    | ({
          [key: string]: Phrase;
      } & {
          [key: number]: string;
      });

While a simple textual phrase consists of a key-value pair, contextualisation as well as pluralization can make your dictionary more complex. In Vay, dictionaries are usually typescript files.

TIP

As long as you do not use plurals or contextual phrases, you can also use JSON files and import them into your TypeScript. See more in the Using JSON dictionaries recipe.

Creating a Dictionary

To create a dictionary, use the defineDictionary function. This function takes two parameters: a locale and an object containing your translations. The locale should be a valid ISO 639 language code, and the translations object should map tokens to their respective strings or functions for dynamic translations.

src/i18n.dictionary.en.ts

// Define a English dictionary
const en = defineDictionary('en', {
    hello: 'Hello',
    goodbye: 'Goodbye',
});

src/i18n.dictionary.es.ts

// Define a English dictionary
const es = defineDictionary('es', {
    hello: 'Hola',
    goodbye: 'Adiós',
});

INFO

Read more about complex dictionaries in the interpolation, pluralization and context section of the documentation.

Integrating Dictionaries

After defining your dictionaries, pass them to your VayProvider during initialization. This makes all the translations available for use throughout your application.

src/i18n.provider.ts

import { createProvider, defineConfig } from '@vayjs/vay';
import { en } from './18n.dictionary.en';
import { es } from './18n.dictionary.es';

export const i18n = createProvider(
    defineConfig({ defaultLocale: 'en' }),
    // Add your dictionaries here
    en,
    es,
);

src/i18n.dictionary.en.ts

import { defineDictionary } from '@vayjs/vay';

// Define a English dictionary
export const en = defineDictionary('en', {
    hello: 'Hello',
    goodbye: 'Goodbye',
});

src/i18n.dictionary.es.ts

import { defineDictionary } from '@vayjs/vay';

// Define a English dictionary
export const es = defineDictionary('es', {
    hello: 'Hola',
    goodbye: 'Adiós',
});

Dictionaries are a powerful aspect of Vay, enabling you to manage translations effectively across multiple languages. By following these guidelines and leveraging the defineDictionary function, you can create a versatile and comprehensive internationalization solution for your applications.