Context

Contextual translations are essential in internationalization frameworks, allowing applications to provide more accurate and nuanced translations based on the context of use. Vay supports contextual translations, making it straightforward to adapt translations not just to linguistic requirements but also to the situational context in which they are used.

Understanding Contextual Translations

Contextual translations enable you to define multiple versions of a phrase for different contexts. This flexibility is crucial for languages where a word's meaning can change significantly depending on the situation, ensuring your application communicates the intended message accurately.

Defining Context-Sensitive Phrases

In Vay, contextual translations are defined using a special syntax within your dictionaries. By defining phrases as functions, you can dynamically return the appropriate translation based on the provided context.

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

export const i18n = createProvider(
    defineConfig({ defaultLocale: 'en' }),
    defineDictionary('en', {
        greeting: ({ timeOfDay }) => {
            switch (timeOfDay) {
                case 'morning':
                    return 'Good morning';
                case 'evening':
                    return 'Good evening';
                default:
                    return 'Hello';
            }
        },
    }),
);

// Reassign and export the translate function to make it easier to use
export const t = i18n.translate;

Utilizing Context in Translations

To use contextual translations, pass the relevant context information to the translate function. The context is provided as part of the TData object.

// Import the created translation function
import { t } from './i18n.provider.ts';

// Outputs: 'Good morning'
console.log(t('(greeting)', { ctx: { timeOfDay: 'morning' } }));

// Outputs: 'Good evening'
console.log(t('(greeting)', { ctx: { timeOfDay: 'evening' } }));

// Outputs: 'Hello'
console.log(t('(greeting)'));

INFO

The final part of the token of a contextual phrase will be wrapped in parenthesis, eg: token.to.(somewhere). This enables you to see quickly in a glance you are dealing with a contextual phrase.

TIP

Use the ctx key within the TData object to pass context-specific data for dynamic translations.

Using Context for Interpolation

In addition to selecting translations based on context, Vay enables the use of context properties directly within your translations through template literal syntax. This approach combines the flexibility of contextual translations with the dynamic nature of interpolation, allowing for more expressive and adaptable translations.

Defining Interpolated Context-Sensitive Phrases

When defining your dictionary, you can incorporate context properties into your phrases using template literals. This method is particularly useful when the translation text itself needs to dynamically reflect values provided via context.

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

export const i18n = createProvider(
    defineConfig({ defaultLocale: 'en' }),
    defineDictionary('en', {
        hero: { greeting: ({ name, timeOfDay }) => `Good ${timeOfDay}, ${name}!` },
    }),
);

// Simplify translation function usage
export const t = i18n.translate;

In this example, the greeting phrase dynamically incorporates both the name and timeOfDay context properties into the translation.

Passing Context for Interpolation

To utilize this feature, provide the context containing the necessary properties when calling the translate function. Vay seamlessly interpolates these properties into the translation based on your phrase definition.

// Import the created translation function
import { t } from './i18n.provider.ts';

// Outputs: 'Good morning, Alice!'
console.log(t('hero.(greeting)', { ctx: { name: 'Alice', timeOfDay: 'morning' } }));

// Outputs: 'Good evening, Bob!'
console.log(t('hero.(greeting)', { ctx: { name: 'Bob', timeOfDay: 'evening' } }));

By leveraging context for interpolation, you can craft more nuanced and personalized translations. This method is particularly effective in applications where the translation needs to adapt not just to linguistic differences but also to the specific circumstances or preferences of the user.

Best Practices for Contextual Translations

• Clearly Define Contexts: Clearly define and document the contexts used in your application to ensure consistency across translations.
• Keep Contexts Simple: While powerful, contexts should be kept simple to avoid overly complex translation logic that can be hard to maintain.
• Test Thoroughly: Given the dynamic nature of contextual translations, thorough testing is essential to ensure that the correct translations are displayed for each context.

Contextual translations enhance the flexibility and accuracy of your application's internationalization efforts. By carefully defining and using contexts, you can ensure that your application provides the most appropriate translations for any given situation, improving the overall user experience for a global audience.