Skip to content

colorfy-software/localify

Repository files navigation

Localization for React Native made simple.

Current GitHub Actions build status. Current npm package version. PRs welcome!

🎯 Purpose

Localify helps you handle localization in your React Native apps with first class Typescript support: simply autocomplete your way through your translation files.

πŸ—οΈ Installation

yarn add @colorfy-software/localify react-native-localize i18n-js
npx pod-install ios --yes

πŸ’» Usage

Setup

App

// ./index.tsx

import { AppRegistry } from 'react-native'
import Localify from '@colorfy-software/localify'

import App from './src/App'

const translations = {
  en: require('./src/locales/en.ts'),
  de: require('./src/locales/de.ts'),
} as const

Localify.init({
  // mandatory
  translations,
  // optional
  defaultSeparator: '.',
  // optional
  fallback: { languageTag: 'en', isRTL: false },
})

AppRegistry.registerComponent('main', () => App)

Jest

// ./jest.setup.js
// (or wherever you have your Jest config's setupFiles file)

process.env.JEST = true // add this line

With TypeScript & autocomplete

See steps
// ./src/locales/index.ts
import Localify, { ValueMapType, currentLocale, currentLocaleCode } from '@colorfy-software/localify'

// Example of what en.ts has to look like:

// export default {
//   general: {
//     activity: 'Activity',
//     home: 'Home',
//     settings: 'Settings',
//     tips: 'Tips',
//     logout: 'Log out',
//   },
//   errors: {
//     requiredField: 'This field is required',
//     passwordTooLong: 'Password needs to be less than **{{maxLengthValue}}** characters long.',
//     invalidEmail:
//       "Sorry, **{{email}}** is not a valid email address. Please double check the email you've entered and try again.",
//     passwordRules:
//       'Your password must be **at least 8 characters long**, with at least three of the following kinds of characters: **uppercase, lowercase, number, and/or symbols**.',
//   },
// } as const

// πŸ‘† notice the `as const`.

import type en from './en'

type ContextType = keyof typeof en

const getLocalizedString = <
  C extends ContextType,
  K extends keyof typeof en[C],
  V extends ValueMapType<typeof en[C][K] extends string ? typeof en[C][K] : never>,
  R extends typeof en[C][K],
>(
  context: C,
  key: K,
  ...values: keyof V extends never ? [never?] : [V]
): R => Localify.getLocalizedString(context, key, values)

export { currentLocale, currentLocaleCode, getLocalizedString }

This is required so that you can define your preferred language for the TypeScript-powered autocompletion. Now, you'd have to import everything from ./src/locales/index.ts instead of the library, getLocalizedString() being the most important here:

// ./src/App.tsx
import * as React from 'react'
import { StyleSheet, SafeAreaView, Text } from 'react-native'

import { currentLocale, getLocalizedString } from './locales'

export default function App() {
  return (
    <SafeAreaView style={styles.container}>
      <Text>
        {currentLocale()}
        {getLocalizedString('general', 'home')}
        {getLocalizedString('errors', 'invalidEmail', { email: '[email protected]' })}
      </Text>
    </SafeAreaView>
  )
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  box: {
    width: 60,
    height: 60,
    marginVertical: 20,
  },
})

Without TypeScript/autocomplete

See steps
// ./src/App.tsx
import * as React from 'react'
import Localify from '@colorfy-software/localify'
import { StyleSheet, SafeAreaView, Text } from 'react-native'

export default function App() {
  return (
    <SafeAreaView style={styles.container}>
      <Text>
        {Localify.currentLocale()}
        {Localify.getLocalizedString('general', 'settings')}
        {Localify.getLocalizedString('errors', 'passwordTooLong', { maxLengthValue: '50' })}
      </Text>
    </SafeAreaView>
  )
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  box: {
    width: 60,
    height: 60,
    marginVertical: 20,
  },
})

🀝 Contributing

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

πŸ’– Code of Conduct

This library has adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.

πŸ“° License

localify is licensed under the MIT License.