@tcbs/react-native-language-translator

On-device language translation utilities for React Native.

This package provides:

• a native translation bridge for Android and iOS
• a supported languages list for building language pickers
• helpers for generating and applying cached language packs from a source locale

Used in production

This package is used in the Android app Water Tracker for on-device language-pack generation in a React Native workflow.

What it does

Use this package when your app keeps a source dictionary, such as en.json, and generates translated key/value content locally on device.

Typical flow:

1. Keep one source locale in the app bundle.
2. Let the user choose a target language.
3. Download native translation models for that language pair.
4. Translate missing keys on device.
5. Cache translated values locally.
6. Apply the cached language pack to your i18n layer.

Platform support

• Android: Google ML Kit Translate
• iOS: ML Kit Translate through the native bridge

Requirements

• react-native >= 0.72
• iOS deployment target 13.0+

Install

npm i @tcbs/react-native-language-translator

or

yarn add @tcbs/react-native-language-translator

Native setup

Android

• Autolinking registers TcbsLanguageTranslatorPackage
• Native dependency included: com.google.mlkit:translate:17.0.3

iOS

• Podspec included: react-native-language-translator.podspec
• Install pods after adding the package:

cd ios && pod install

Model download note

Translation models are downloaded per language. They are sizeable and should be treated as runtime assets, not bundled app assets.

Plan for:

• first-use download time
• network availability checks
• local storage usage
• user messaging around model download status

Supported languages

The package exports a ready-to-use language list from supportedLanguages.

Example item:

{
  "code": "es",
  "name": "Spanish",
  "flag": "🇪🇸"
}

Useful helpers:

• getSupportedLanguages(options?)
• isLanguageSupported(languageCode)
• getLanguageByCode(languageCode)
• normalizeLanguageCode(languageCode)
• resolveTranslatorLanguageCode(languageCode)

Built-in alias mapping:

• hn -> hi
• od -> or

API

createNativeTranslatorModule(options?)

Returns a native translator adapter with:

• getSupportedLanguages()
• getDownloadedLanguages()
• isSupported(source, target)
• prepareLanguagePair(source, target)
• translateBatch(texts, source, target)

ensureLanguagePackReady(input)

Generates missing translations from a source dictionary, stores them through your repository adapter, and returns coverage information.

applyCachedLanguagePack(input)

Loads cached translations from your repository into your i18n adapter.

Basic example

import {
  createNativeTranslatorModule,
  getSupportedLanguages,
  isLanguageSupported,
  resolveTranslatorLanguageCode,
} from '@tcbs/react-native-language-translator';

const selectedLanguage = 'od';
const targetLanguage = resolveTranslatorLanguageCode(selectedLanguage);

if (!isLanguageSupported(targetLanguage)) {
  throw new Error('Unsupported language');
}

const languageOptions = getSupportedLanguages({ includeEnglish: true });
const translator = createNativeTranslatorModule();

await translator.prepareLanguagePair('en', targetLanguage);

const translated = await translator.translateBatch(
  ['Settings', 'Store'],
  'en',
  targetLanguage,
);

Language-pack example

import {
  applyCachedLanguagePack,
  createNativeTranslatorModule,
  ensureLanguagePackReady,
} from '@tcbs/react-native-language-translator';

await ensureLanguagePackReady({
  sourceLanguage: 'en',
  targetLanguage: selectedCode,
  sourceDictionary: enJson,
  i18n,
  repository: localizedOverrideRepository,
  nativeModule: createNativeTranslatorModule(),
});

applyCachedLanguagePack({
  languageCode: selectedCode,
  i18n,
  repository: localizedOverrideRepository,
});

Adapter expectations

ensureLanguagePackReady expects:

• an i18n adapter with getResourceBundle() and addResourceBundle()
• a repository adapter with getMapForLanguage() and upsertMany()
• a nativeModule adapter returned by createNativeTranslatorModule()

This keeps the package storage-agnostic and compatible with common i18n setups.

Development

To regenerate the published JS and type declarations:

npm run build

Sponsor

If this package is useful to you, consider supporting the work here: sponsors/subraatakumar

License

MIT