@resourge/translations NPM

@resourge/translations

@resourge/translations is a typeScript library designed to manage translations in your application. It provides a flexible setup for handling multilingual content and offers an easy-to-use interface for retrieving and managing translations.

Installation

Install using Yarn:

yarn add @resourge/translations

or NPM:

npm install @resourge/translations --save

Usage

const translationsInstance = SetupTranslations({
  langs: ['en', 'fr', 'es'],
  defaultLanguage: 'en',
  plugins: [....],
  // This
  translations: {
	greeting: {
	  en: 'Hello',
      fr: 'Bonjour',
      es: 'Hola',
	},
	goodbye: {
	  en: 'Goodbye',
      fr: 'Au revoir',
      es: 'Adiós',
	},
	homeScreen: {
	  welcome: {
	    en: 'Welcome',
	    fr: 'Bienvenue',
	    es: 'Bienvenido',
	  },
	},
  },
  // or
  load: {
    request: async () => {
      // Example: Fetch translations from a server
      const response = await fetch('/translations');
      const translations = await response.json();
      return translations;
    },
    structure: {
      greeting: 'Hello',
      goodbye: 'Goodbye',
    }
  }
});

Accessing Translations

Once you have an instance, you can access translations and keys:

const greetingTranslation = translationsInstance.T.greeting; // Access translations
const greetingTranslation2 = translationsInstance.t('greeting'); // Access translations
const greetingKey = translationsInstance.K.greeting; // Access translation keys

Changing Language

You can change the current language:

await translationsInstance.changeLanguage('en'); // Change to English

Events

SetupTranslations supports events like languageChange and missingRequestKeys. You can listen to these events:

translationsInstance.addEventListener('languageChange', (language: string) => {
  console.log(`Language changed to: ${language}`);
});

translationsInstance.addEventListener('missingRequestKeys', () => {
  console.log('Missing translation keys requested.');
});

API Reference

SetupTranslations

SetupTranslations(config: SetupTranslationsConfig) => SetupTranslationsInstance Creates a new instance of SetupTranslations with the provided configuration.

SetupTranslationsInstance

Properties

isReady: boolean: Indicates if translations are ready.
config: SetupConfig<Langs, Trans>: Configuration object.
language: string: Current language.
languages: string[]: Available languages.
T: Record<string, any>: Translations object.
t: (key: string, values?: Record<string, any>) => string: Function to return the translation.
K: Record<string, any>: Translations keys.

Methods

changeLanguage(lang: string): Promise<void>: Changes the current language.
addEventListener(event: EventType, callback: Function): () => void: Adds an event listener.

Plugins

SetupTranslations allows you to add plugins or custom plugins for handling language changes, translation gets, translation sets and config modifications.

htmlLanguage

htmlLanguage plugin is a simple plugin designed to handle setting the HTML lang attribute based on the current language. It ensures that the lang attribute of the HTML element reflects the selected language, providing accessibility benefits and aiding in language-specific styling.

htmlLanguage plugin will automatically:

Set the lang attribute of the <html> element to the selected language.
Update the lang attribute whenever the language changes.

Usage

import { htmlLanguage } from '@resourge/translations';

const translationsConfig = SetupTranslations({
  langs: ['en', 'fr'],
  defaultLanguage: 'en',
  translations: {
    en: {
      greeting: 'Hello!'
    },
    fr: {
      greeting: 'Bonjour!'
    }
  },
  plugins: [htmlLanguage()]
});

Additional Notes

Make sure the htmlLanguage plugin is added to your translation setup using SetupTranslations.
The lang attribute of the HTML element is essential for screen readers and other accessibility tools.
The plugin provides a convenient way to ensure the correct language is reflected in the HTML for improved accessibility and language-specific styling.

languageLocalStorage

languageLocalStorage plugin is designed to store and retrieve translations in the browser's local storage. This allows for persistent language selection across sessions, enhancing the user experience by remembering the chosen language.

languageLocalStorage plugin will automatically:

Retrieve the selected language from local storage and set it as the default language.
Store translations in local storage when they are set.
Retrieve translations from local storage if available, falling back to the provided translations.

Usage

import { languageLocalStorage } from '@resourge/translations';

const translationsConfig = SetupTranslations({
  langs: ['en', 'fr'],
  defaultLanguage: 'en',
  translations: {
    en: {
      greeting: 'Hello!'
    },
    fr: {
      greeting: 'Bonjour!'
    }
  },
  plugins: [languageLocalStorage()]
});

Additional Notes

The languageLocalStorage plugin provides a way to store translations in the browser's local storage.
It ensures that the selected language is persisted across sessions, improving user experience.
Make sure the languageLocalStorage plugin is added to your translation setup using SetupTranslations.

navigatorLanguageDetector

navigatorLanguageDetector plugin is designed to detect the user's preferred language based on their browser settings. It utilizes the navigator object to retrieve the language information.

navigatorLanguageDetector plugin will automatically:

Detect the user's preferred language based on their browser settings.
Apply the detected language if it matches any of the configured languages.
Fall back to the default language if the detected language is not supported.

Usage

import { navigatorLanguageDetector } from '@resourge/translations';

const translationsConfig = SetupTranslations({
  langs: ['en', 'fr'],
  defaultLanguage: 'en',
  translations: {
    en: {
      greeting: 'Hello!'
    },
    fr: {
      greeting: 'Bonjour!'
    }
  },
  plugins: [navigatorLanguageDetector()]
});

Additional Notes

The navigatorLanguageDetector plugin automatically detects the user's preferred language based on their browser settings.
It allows for custom modification of the detected language before applying it to the translation setup.
Ensure that the navigatorLanguageDetector plugin is added to your translation setup using SetupTranslations.

Custom Plugins

navigatorLanguageDetector, htmlLanguage, languageLocalStorage plugins are just examples of a translation plugin. You can create your own custom plugins to extend the functionality of your translation setup.

const customPlugin: TranslationPlugin = {
  config: (config) => {
    return {
      ...config,
      // Add custom config modifications here
    };
  },
  onLanguageChange: (language) => {
    console.log(`Language changed to: ${language}`);
    // Add custom logic when language changes
  },
  onTranslationGet: (keys) => {
    console.log(`Translations requested for keys: ${keys.join(', ')}`);
    // Add custom logic for translation get events
  },
  onTranslationSet: (keys) => {
    console.log(`Translations set for keys: ${keys.join(', ')}`);
    // Add custom logic for translation set events
  },
};

const translationsInstance = SetupTranslations({
  langs: ['en', 'fr', 'es'],
  defaultLanguage: 'en',
  plugins: [customConfigPlugin],
  // Other configuration options...
});

Custom Translations

SetupTranslations includes predefined custom translation functions for common scenarios such as gender and plural. These custom types provide a structured way to manage translations for gender-specific content and plural forms.

Gender Translation function

The gender function handles translations for genders such as "female" and "male". It provides a convenient way to retrieve the appropriate translation based on the specified gender.

Example:

import { gender, SetupTranslations } from '@resourge/translations';

const translationsInstance = SetupTranslations({
  langs: ['en', 'fr'],
  defaultLanguage: 'en',
  translations: {
    trans_message: gender({
      female: {
        en: 'Female',
        fr: 'Femme',
      },
      male: {
        en: 'Male',
        fr: 'Homme',
      },
    }),
    // Add other translations as needed
  },
  // Other configuration options...
});

translationsInstance.T.trans_message({
  gender: 'male' // 'female'
})

Plural Translation function

The plural function handles translations for plural forms. It allows you to specify translations for different counts and automatically selects the appropriate translation based on the count provided.

Example:

import { plural, SetupTranslations } from '@resourge/translations';

const translationsInstance = SetupTranslations({
  langs: ['en', 'fr'],
  defaultLanguage: 'en',
  translations: {
    trans_message: plural({
      one: {
        en: '1 item',
        fr: '1 article',
      },
      other: {
        en: '{count} items',
        fr: '{count} articles',
      },
      two: {
        en: '{count} items',
        fr: '{count} articles',
      },
      zero: {
        en: '{count} items',
        fr: '{count} articles',
      },
    }),
    // Add other translations as needed
  },
  // Other configuration options...
});

translationsInstance.T.trans_message({
  count: 0 // number
})

Create Your Own Custom Translation function

You can create your custom translation function tailored to your application's specific needs. Here's how you can define and use your own custom translation type:

Example

Let's say you want to create a custom translation type for greetings based on the time of day.

Define the custom translation type timeOfDayGreetings:

import { CustomMethods } from '@resourge/translations';

export const timeOfDayGreetings = CustomMethods.add<
  'timeOfDay',
  {
    morning: string,
    afternoon: string,
    evening: string,
    night: string,
  }
>(
  'timeOfDay',
  (value, params) => {
    const time = params.timeOfDay;
    return value[time];
  }
);

Usage example:

const translationsInstance = SetupTranslations({
  langs: ['en', 'fr'],
  defaultLanguage: 'en',
  translations: {
    trans_message: timeOfDayGreetings({
      morning: {
        en: 'Good morning!',
        fr: 'Bonjour!',
      },
      afternoon: {
        en: 'Good afternoon!',
        fr: 'Bon après-midi!',
      },
      evening: {
        en: 'Good evening!',
        fr: 'Bonsoir!',
      },
      night: {
        en: 'Good night!',
        fr: 'Bonne nuit!',
      },
    }),
    // Add other translations as needed
  },
  // Other configuration options...
});

translationsInstance.T.trans_message({
	timeOfDay: 'morning' // afternoon || evening || night
})

viteTranslationPlugin

viteTranslationPlugin, is designed to enhance Vite applications by optimizing translation loading for production. It provides seamless integration for custom translations and ensures efficient handling of translation files. More documentation