Requirements
Install Lokalise (https://github.com/lokalise/lokalise-cli-2-go)
Install
npm i @zauberware/react-i18n --save
yarn add @zauberware/react-i18n
Create Project
Create Project at https://lokalise.com. Copy token and project id to your .env file. Go to personal profile to grap token and to project settings to grap project id.
.env
Configure and put these env variables to your .env file.
Common
REACT_APP_LOKALISE_TOKEN=token
REACT_APP_LOKALISE_PROJECT_ID=projectid
REACT_APP_BRANCHES=false
REACT_APP_LOCALES=["de", "en", "fr"]
REACT_APP_DEFAULT_LOCALE=de
REACT_APP_ENV=development
REACT_APP_S3_BUCKET=zwt.locales.test/lokalise
REACT_APP_SRC_INPUT=./src/**/*.js
React
REACT_APP_LOCALES_BUILD_PATH=public/locales
REACT_APP_LOCALES_PUSH_PATH=./.locales
REACT_APP_ENV=development
React-Native
REACT_APP_LOCALES_BUILD_PATH=www/locales
REACT_APP_LOCALES_PUSH_PATH=.locales
package.json scripts
Put these scripts into your root package.json
"locales-push": "npm explore @zauberware/react-i18n -- npm run locales-push --env=$PWD",
"locales-parse": "npm explore @zauberware/react-i18n -- npm run locales-parse --env=$PWD",
"locales-push-files": "npm explore @zauberware/react-i18n -- npm run locales-push-files --env=$PWD",
"locales-pull-files": "npm explore @zauberware/react-i18n -- npm run locales-pull-files --env=$PWD"
Develop your app!
React
import React, { Suspense } from "react";
<Suspense fallback="Loading">
<App />
</Suspense>
import i18n, { useTranslation } from "@zauberware/react-i18n/web";
const { t } = useTranslation("app", { useSuspense: true });
{t('key')}
{t('key', {maxLength: 150})}
{t('key', {defaultValue: 'XYZ'})} // helps coding a lot!
React Native
import i18n, { useTranslation } from "@zauberware/react-i18n/mobile";
Flows
Create locales
Based on the env variable "REACT_APP_LOCALES", it will create the locales you want to use for your project. You can re-run this command if you want to add locales.
npm run locales-push
Use branches [optional]
Go to project settings. Check "branching", save. Create branches you need e.g. development, staging, production. Set env variable "REACT_APP_BRANCHES" to true to tell React to download env specific translations. Set "REACT_APP_ENV" to the env you are currently using.
All package.json commands need to add --branch=staging to tell Lokalise which env we are talking to.
Parse translation keys
Will create parsed files to upload/compare with Lokalise. You can configure where the parser should create the files with "REACT_APP_LOCALES_PUSH_PATH". These files be used to push/cleanup keys. The format of these JSON files is structured. Parser will collect keys, validation limits etc.
npm run locales-parse
Push translation keys
Push translations keys/files from "REACT_APP_LOCALES_PUSH_PATH".
npm run locales-push-files
Go to your lokalise project and check whether the upload was successful.
Pull translation keys
Pull keys to directory. Please use public/locales for React web projects! You have to pull locales, otherwise fallback files won't work! These files will be put into the build as fallback JSON files. The format of these JSON files is flat (key: value).
npm run locales-pull-files
S3 Bucket sync
Enable S3 Integration in your lokalise project.
Specify which bucket should be used declared with "REACT_APP_S3_BUCKET". Bucket needs to be public!
You can trigger s3 sync by clicking "Download" and selecting "Amazon S3" as export.
Please use project_id/%LANG_ISO% as file structure. Please use project_id/env/%LANG_ISO% when using branches. Please use format "JSON (.json)"! Click "build only" to trigger s3.
You can ask support to enable s3 sync on other events like "translations updated".
Translator Role
Create Translator User + Translator Role, which limitted permissions. Can only edit locales. Cannot create locales or create keys. Invite client to start translating.
Cleanup keys
Generate keys npm run locales-parse.
npm run locales-push-files --cleanup=true will remove all remote keys which do not exist anymore