React Native Poco Loco

Simpliest localization for your ReactNative/React app.

Table of Contents

• Introduction
  • Features
• Installation
  • Using package manager
  • IOS platform
• How it works
  • Basic Usage (Without Google Sheets Integration)
  • Advanced Usage (Google Sheets Integration)
• Workflow with integrated scripts
  • Create Local Translation Files
  • Fill Google Spreadsheet with Translation
  • Update Local Translation Files
• API

Introduction

Welcome to react-native-poco-loco, an open-source library designed to streamline the internationalization process for both mobile (React Native) and web projects. This library facilitates easy translation management and synchronization, allowing developers to effortlessly maintain multilingual support for their applications.

Features

• Automated Localization File Generation: react-native-poco-loco provides pre-configured scripts that automate the creation of local translation files based on a master file. Developers can easily generate language-specific files without manual intervention.

• Cross-Platform Compatibility: Works seamlessly with both mobile (React Native) and web applications, ensuring a unified internationalization solution for diverse project environments.

• Support Google Sheets Integration: react-native-poco-loco includes scripts for synchronizing translations between local files and Google Sheets. This enables collaboration with multiple translators who can conveniently work on translations within a shared Google Sheets document.

• Translator Workflow: Facilitates collaboration between developers and translators using Google Sheets. Translators can work on translations in a familiar spreadsheet environment, making it accessible and user-friendly. Developers can synchronize the translations with their local files using provided scripts

Installation

Package manager

The easiest way to install is use your package manager:

npm install react-native-poco-loco

or

yarn add react-native-poco-loco

IOS Platform

An additional step to install native modules for an IOS project:

cd ios && pod install && cd ..

How it works

react-native-poco-loco is flexible and can be used in different ways based on your project's needs. Whether you want a simple integration without Google Sheets or a collaborative approach with Google Sheets, react-native-poco-loco can adapt to your workflow.

Basic Usage

Initialization of LocalizationService:

To get started with react-native-poco-loco's LocalizationService, follow these steps:

1. Create Translation Files:

• Prepare translation files in JSON format. For example:

{
  "greeting": "Hello",
  "farewell": "Goodbye",
  "auth": {
    "success": "Success",
    "error": "Error"
  }
}

2. Import LocalizationService:

• Import the LocalizationService from the 'react-native-poco-loco' library.
• Import your translation files.

import { LocalizationService, IOptions } from 'react-native-poco-loco';
import * as en from './en.json';
import * as uk from './uk.json';
import * as uaSecond from './uaSecond.json';

3. Initialize LocalizationService:

• Create an instance of LocalizationService and pass the translation files as arguments.

export const t = new LocalizationService({
  en,
  uk,
  'uk-UA': uaSecond,
});

4. Optional Configuration (for both platforms):

• Users can pass an optional configuration object, including a custom language interface.

const options: IOptions = {
  deviceLanguage: 'uk-UA', // Detected language interface
};

export const t = new LocalizationService(
  {
    en,
    uk,
    'uk-UA': uaSecond,
  },
  options
);

Note: The library has built-in functionality to detect the device language only for mobile!

Now, you're ready to use the t instance for internationalization in your project that has access the keys of the localized strings.

<Text>{t.greeting}</Text>

Advanced Usage (Google Sheets Integration)

Follow these steps to integrate Google Sheets with the localization library for dynamic translation updates.

1. Create a New Project in Google Cloud Console

   A project organises all Google Cloud resources. Create a new project in the Google Cloud Console by following the steps outlined in the Google Cloud documentation.

2. Enable Google Sheets API under the Created Project

• Navigate to the API Console.
• Click ENABLE APIS AND SERVICES and enable the Google Sheets API.

3. Create specific credentials according to the requirement

   Credentials are necessary to obtain an access token from Google's authorization server. Follow these steps:

   • Configure the OAuth consent screen by referring to the Google Workspace guide.
   • After the configuration of the OAuth consent screen, create an OAuth client ID credential as you would for Web application.

   NOTE: To simplify the process of copying the access token, use the prepared redirect URI: https://hostingpocolocowebpage.web.app/. Alternatively, you can use your own redirect URI and the access token can be extracted from the URL.

4. Create a spreadsheet on Google Drive

   Create a spreadsheet and configure access to it according to your needs (by link or restricted).

5. Create a poco-loco.config.json file in the root of the project

   Create a configuration file with the following key-value pairs:

{
  "clientId": "your OAuth Client ID",
  "redirectUri": "https://hostingpocolocowebpage.web.app/", // specified when creating the OAuth Client ID in Authorized redirect URIs
  "spreadsheetId": "your spreadsheet ID", // can be found from the URL of the spreadsheet
  "mainFilePath": "./src/translations/en.json", // relative path to the main language file
  "languages": ["fr", "de", "es", ...] // array of languages
}

6. Update package.json

{
  ...
"scripts": {
  ...
"translations:generate": "node ./node_modules/react-native-poco-loco/lib/module/google-sheets-createLocalTranslationsFiles.js",
"translations:fill-google-sheet": "node ./node_modules/react-native-poco-loco/lib/module/google-sheets-fillingTranslationsSheets.js",
"translations:update": "node ./node_modules/react-native-poco-loco/lib/module/google-sheets-updateLocalTranslationsFiles.js"
}
...
}

Workflow with integrated scripts

1. Create Local Translation Files:

   npm run translations:generate

Generates translation files in the directory with the main translation file. The languages are defined in the poco-loco.config.json file.

2. Fill Google Spreadsheet with Translation:

   npm run translations:fill-google-sheet

Populates the Google spreadsheet with translations from local files.

3. Update Local Translation Files:

   npm run translations:update

Updates local translation files with content from the Google Spreadsheet.

API

• setLanguage(languageCode: string) - manually sets a particular language for the application.

  Note: To reflect changes in the UI, ensure to trigger a rerender.

• getAvailableLanguages(): strings[] - returns an array of languages available in the translation library

• getLanguage(): string - returns the currently displayed language

• getDeviceLanguage(): string - returns the current language of the device.

  Note: The default value for web is "en-US".

• getString(key: string, interpolationParams?: ITranslationParams): string - returns the passed string replacing its placeholders with the other arguments strings.

Example

{
  "сongratulations": "Congratulations {name} you win {prize}."
}

const firstName = 'Poco';
const hat = '"Mandalorian Helmet"';

console.log(t.getString('сongratulations', { name: firstName, prize: hat })); // Congratulations Poco you win "Mandalorian Helmet".
console.log(t.getString('auth.success')); // Success
console.log(t.getString('firstKey.secondKey')); // firstKey.secondKey

⚠️ Pay attention ⚠️

When working with local files and sheets, we follow the "single file" principle. The main language file contains the current keys, and it serves as the reference for all other files.

If you've made changes to the keys in the main language file and want to update the files derived from it, follow these steps:

   1) npm run translations:generate
   2) npm run translations:fill-google-sheet
   3) npm run translations:update

Error Handling Guidance

If you encounter an error message while running translations:update command, ensure that all translation files are updated with the latest keys from the main file. This step is crucial for preventing discrepancies and maintaining synchronization across your translation files.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library