translation-service-fe-lib README

translation-service-fe-lib is a lightweight React library that provides a simple and efficient solution for managing translations in your React applications. It handles translations using a React context and custom hooks, making it easy to integrate into your projects.

Installation

To install this library, you can use the following command:

npm install translation-service-fe-lib

Usage

To use the library, you'll need to import and utilize the TranslationsProvider component and the useTranslations custom hook in your React application.

Setting up the TranslationsProvider

Wrap your application's root component with the TranslationsProvider component, and pass the required properties:

import { TranslationsProvider } from 'translation-service-fe-lib';

// Your translations dictionary
const translationsDictionary = {...};

// Your app language key
const appLanguage = 'your-app-language-key';

// Your language configuration
const languageConfig = {...};

// Your custom translation handler implementing the ITranslationHandler interface
const translationHandler = new CustomTranslationHandler();

ReactDOM.render(
  <TranslationsProvider
    translationsDictionary={translationsDictionary}
    appLanguage={appLanguage}
    languageConfig={languageConfig}
    translationHandler={translationHandler}
  >
    <App />
  </TranslationsProvider>,
  document.getElementById('root')
);

Using the useTranslations hook

To access the translation functions in your components, import and use the useTranslations custom hook:

import { useTranslations } from 'translation-service-fe-lib';

function MyComponent() {
  const { translate, currentLanguage, setCurrentLanguage } = useTranslations();

  // Example usage
  const translatedText = translate('module.exampleLabel', { param1: 'value1' });

  return (
    <div>
      <p>{translatedText}</p>
    </div>
  );
}

API

TranslationsProvider

This component provides the translations context to your React application. It accepts the following properties:

• children: The React component(s) to render.
• translationsDictionary: The translations dictionary object.
• appLanguage: A unique key to store the user's selected language in the localStorage.
• languageConfig: The language configuration object, containing information about the available languages and the default language.
• translationHandler: A custom translation handler implementing the ITranslationHandler interface, responsible for fetching, storing, and loading translations.

useTranslations

This custom hook allows you to access the translation functions in your components. It returns an object containing the following properties:

• translate: A function that accepts a translation key and an optional object with parameters, and returns the translated text for the current language.
• currentLanguage: A string representing the current language code.
• setCurrentLanguage: A function that accepts a new language code and updates the current language.

Commands

The following npm commands are available in this package:

1. build:pre

This command renames the node_modules_backup folder to node_modules. It's useful to restore the node_modules folder before building the project, in case it was backed up previously.

npm run build:pre

2. build

This command compiles your TypeScript files using the TypeScript compiler (tsc). The configuration is read from the tsconfig.json file in your project directory.

npm run build

3. build:after

This command renames the current node_modules folder to node_modules_backup. It's useful for backing up the node_modules folder after the build process to prevent unnecessary dependencies from being included in your deployment package.

npm run build:after

4. build:all

This command runs all of the above commands in sequence: build:pre, build, and build:after. It's a convenient way to run the entire build process with a single command. Used for local development (using npm-link) in order to not include node_modules folder

npm run build:all

Use of build commands:

• initial use (when you build the library for first time you should install all the packages which will create node_modules folder, build the library and rename node_modules folder to node_modules_backup):

npm install
npm run build
npm run build:after

• common use (when you usually build the library you should use npm run build:all in order to rename node_modules_backup folder to node_modules, build the library and again rename node_modules folder to node_modules_backup):

npm run build:all

Contributing

If you have any suggestions, improvements, or bug reports, please feel free to submit an issue or a pull request on the project's repository. Your feedback is highly appreciated!