API Reference

This section documents the essential functions provided by Vay, detailing their usage, parameters, and return types to help you integrate and leverage the full capabilities of the library for internationalization.

General Overview

Vay.js offers a concise yet powerful set of functions designed to facilitate the creation, management, and utilization of internationalized content within your applications.

createProvider

Creates and configures a VayProvider, initializing it with dictionaries and a global configuration.

Type:

createProvider<Dict extends Dictionary, Phrases = Dict['phrases']>(config: VayConfig,...dictionaries: Dict[]): VayProvider

Template:

• Dict: (Type: Dictionary): A Dictionary returned by the defineDictionary function.
• Phrases: (Type: Record<string, Phrase>): The phrases of the dictionaries extracted

Parameters:

• config (type: VayConfig): Configuration object for setting up the provider, including the default locale and other global settings.
• ...dictionaries (type: Dictionary[]): One or more dictionaries containing the translations for various languages.

Returns:

• VayProvider: An instance of the translation provider, equipped with methods for translating text, setting the current language, and accessing the configuration.

Example:

import { createProvider, defineConfig, defineDictionary } from '@vayjs/vay';

export const i18n = createProvider(
    // Define config and dictionary
    defineConfig(),
    defineDictionary('en', { token: 'Phrase' }),
);

defineDictionary

Utility function for defining a dictionary for a specific locale. It assists with TypeScript type inference for translations.

Type:

defineDictionary<T extends Record<string, Phrase>>(locale: ISO639Code, phrases: T): Dictionary<T>

Template:

• T: The phrases passed to the Dictionary. TypeScript infers these phrases and enables the strongly typed token system.

Parameters:

• locale (type: ISO639Code): A valid ISO 639 language code representing the dictionary's language.
• phrases (type: T): An object mapping tokens to their translated phrases or functions for dynamic and contextual translations.

Returns:

• Dictionary<T>: A dictionary object ready to be used with a VayProvider.

Example:

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

export const en = defineDictionary('en', {
    token: 'Phrase',
    people: {
        0: 'No people',
        1: 'More people',
    },
});

defineConfig

Generates a configuration object for initializing the Vay provider, ensuring type safety and autocomplete in IDEs.

Type:

defineConfig(props?: Partial<VayConfig>): VayConfig;

Parameters:

• props (type: Partial<VayConfig>): Optional properties to override default configuration settings.

Returns:

• VayConfig: A complete configuration object for use with the createProvider function.

Example:

import { defineConfig, getBrowserDefaultLanguage } from '@vayjs/vay';

export const providerConfig({
    defaultLocale: getBrowserDefaultLanguage(),
    quiet: false,
})

VayProvider.translate

Accesses a phrase from the provided token, optionally incorporating interpolation, pluralization, or an overridden locale.

Type:

translate<Token extends PropertyPath<Phrases>>(token: Token, tData: TData | undefined, locale?: ISO639Code): string

Template:

• Token: (type: PropertyPath<Phrases>): The token used to identify the correct phrase.

Parameters:

• token: (type: PropertyPath<Phrases>): The token used to identify the correct phrase.
• [tData]: (type: Record<PropertyKey, unknown>): Additional data that can be passed to the function to configure interpolation, context as well as pluralization.
• [locale]: (type: ISO639Code): A optional locale to override the provider's locale.

Returns:

• string: A string if a match was found, the token itself if no match was found or if there was an error during translation.

Example:

import { t } from 'i18n.provider.ts';

console.log(t('token')); // Outputs: 'Phrase'

createStaticProvider

Creates a static translation provider designed to simplify the translation of static web pages or elements within an application. This function is particularly useful for projects where translations need to be applied directly to the DOM.

Type:

createStaticProvider<Dict extends Record<string, Phrase>>(provider: VayProvider<Dict>): StaticProvider

Template:

• Dict: (type: Dictionary): A Dictionary returned by the defineDictionary function.

Parameters:

• provider (type: VayProvider<Dict>): An instance of the VayProvider created with the createProvider function. This provider should already be configured with the necessary dictionaries and settings.

Returns:

• VayStaticProvider: An object containing methods to handle the static translation process. The most notable method is render, which applies translations to elements marked for translation within a specified DOM tree.

Example:

import { createStaticProvider } from '@vayjs/vay';
import { i18n } from 'i18n.provider.ts';

const { render } = createStaticProvider(i18n);

window.addEventListener('DOMContentReady', () => {
    render(document.documentElement);
});

getBrowserDefaultLanguage

Retrieves the browser's default language setting, providing a convenient method to align your application's default language with the user's preference. This function is particularly useful for initializing the application with a locale that best matches the user's browser settings.

Type:

getBrowserDefaultLanguage(): ISO639Code

Returns:

• ISO639Code: The ISO 639-1 language code representing the browser's default language. If the browser's language cannot be determined, or if it's not supported by your application, a fallback value ('en' for English) is returned.

Example:

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

const locale = getBrowserDefaultLanguage();

console.log(locale);
// Outputs the default locale when in a browser environment,
// 'en' as fallback value when not in a browser environment