Skip to content

marchintosh94/i18nPro

Repository files navigation

@marchintosh94/i18n-pro

Introduction

i18nPro is a powerful internationalization library for web applications. It provides a seamless way to manage translations and pluralization in multiple languages. This is the core library and this documentation will guide you through the installation, setup, and usage of i18nPro.

πŸ“„ Table of Contents

  1. Installation
  2. Configuration
  3. Usage
  4. React
  5. License

Installation

npm install @marchintosh94/i18n-pro
# or
yarn add @marchintosh94/i18n-pro

Configuration

  • defaultLocale (string): The default language to use if no language is specified.

Import the i18nPro module and set your desired configuration in the entry point of your application:

// src/index.ts

import { i18nPro } from '@marchintosh94/i18n-pro'

i18nPro.defaultLocale = 'en-US'

//... other

Usage

Load external translation: loadMessages

This method allows to change current locale and load the dictionary from remote server via HTTP.

import { i18nPro } from '@marchintosh94/i18n-pro'


// Set the locale and load translation dictionary from external url
await i18nPro.loadMessages('en', 'https://cdn.site.dev/translations/en.json')
const welcome = i18nPro.t('welcome');

Load translation manually: loadLocalMessages

This method allows to change current locale andload the dictionary directly from the local environment.

import { i18nPro } from '@marchintosh94/i18n-pro'


// Set the locale and load translation dictionary as string that contains the JSON object
await i18nPro.loadLocalMessages('en', '{"Hi": "Hi"}')
// or with a JSON object Record<string, string | number>
const dictionary: Record<string, string | number> = {"Hi": "Hi"}
await i18nPro.loadLocalMessages('en', dictionary)
const welcome = i18nPro.t('Hi');

Change Language: changeLanguage

This method allows to change current locale and dynamically load the dictionary from the local environment or remote server based on the argouments passed to the function.

import { i18nPro } from '@marchintosh94/i18n-pro'


// Set the locale and load translation dictionary as string that contains the JSON object
await i18nPro.changeLanguage('en', '{"Hi": "Hi"}')
// or with a JSON object Record<string, string | number>
const dictionary: Record<string, string | number> = {"Hi": "Hi"}
await i18nPro.changeLanguage('en', dictionary)
const welcome = i18nPro.t('Hi');

Translate: t

Once the dictionary is loaded and the locale is set, the t method will translate the key that is passed in if a match is found, otherwise it will return the key as default value.

import { i18nPro } from '@marchintosh94/i18n-pro'

const dictionary: Record<string, string | number> = {"Hi": "Hi"}
await i18nPro.changeLanguage('en', dictionary)

//
const welcome = i18nPro.t('Hi');

Pluralization

{
    "apple": "0 apples| 1 apple | 2 apples ",
}
const apples = i18nPro.t('apple', 1);
// Output: "I'd like 1 apples"

Dynamic Data

{
    "tranlsation_key": "Hi, my name is {my_name}",
}
const apples = i18nPro.t('tranlsation_key', { my_name: "Carlos" });
// Output: "Hi, my name is Carlos"

JSON Translations

i18nPro accepts as translation dictionary a JSON with the following format:

Simple

{
    "tranlsation_key": "translation_value",
    "tranlsation_key2": "translation_value2",
    "tranlsation_key3": "translation_value3",
}

Pluralization

The result of the translation will be calculated once t method will be used with the pluralization argoument.

{
    "tranlsation_key": "One | Two | Three",
}

Dynamic Data

The value in the curly braces will be replaced once the t method will be used with the related argoument.

{
    "tranlsation_key": "Hi, my name is {my_name}",
}

React - I18nPro-React

@marchintosh/i18n-pro-react

This is the implementation of main library for React. i18nPro-react exposes all the core functionalities and utilities to adapt them to React ecosystem.

License

This project is licensed under the MIT License.