I18N for Mobile app

TODO list for i18n:

• detect language from user
• handle display for static messages
• handle display for dynamic messages
• handle for external packages
  • axios request with locale in header
  • dayjs display

Supported locales

Define supported locales for your app

export enum SupportedLocale {
  vi = 'vi',
  en = 'en',
}
export const DEFAULT_CONTENT_LOCALE = SupportedLocale.vi
export const FALLBACK_DETECTED_LOCALE = SupportedLocale.en

helpers

export function isLocaleSupported(locale: string): boolean {
  return Object.values(SupportedLocale).includes(locale as SupportedLocale)
}

export function getSupportedLocale(locale: string): SupportedLocale | undefined {
  return isLocaleSupported(locale) ? locale as SupportedLocale : undefined
}

Language detection

export function updateLocaleForUI(locale: SupportedLocale | string) {
  dayjs.locale(locale)
  i18nCore.activate(locale)
}

i18n.ts - somehow these code is loaded on app opened

// init i18n
; (() => {
  const savedLocale = getSavedLocale()
  // console.log('savedLocale', savedLocale)
  updateLocaleForUI(savedLocale)
  setAxiosDefaultLocale(savedLocale)
})()

import { NativeModules, Platform } from 'react-native'
import * as Localization from 'expo-localization'
import { FALLBACK_DETECTED_LOCALE, SupportedLocale } from '@/constants/locales'
import { isLocaleSupported } from './helpers/locale.helper'

/**
 * Get device locale with fallback to default
 * @returns Always returns a SupportedLocale
 */
export function getDeviceLocaleWithFallback(): SupportedLocale {
  const locale = getDeviceLocale()
  return isLocaleSupported(locale) ? locale as SupportedLocale : FALLBACK_DETECTED_LOCALE
}

function getDeviceLocale(): SupportedLocale | string {
  try {
    // Method 1: Use Expo Localization (most reliable)
    const locales = Localization.getLocales()
    if (locales && locales.length > 0) {
      return normalizeLocale(locales[0].languageTag)
    }

    // Method 2: Try to get locale from native modules
    if (Platform.OS === 'ios') {
      const locale
        = NativeModules.SettingsManager?.settings?.AppleLocale
        || NativeModules.SettingsManager?.settings?.AppleLanguages?.[0]

      if (locale) {
        return normalizeLocale(locale)
      }
    } else if (Platform.OS === 'android') {
      const locale = NativeModules.I18nManager?.locale

      if (locale) {
        return normalizeLocale(locale)
      }
    }

    // Method 3: Fallback to Platform.constants.systemLocale
    if (Platform.constants && 'systemLocale' in Platform.constants) {
      const systemLocale = (Platform.constants as any).systemLocale
      if (systemLocale) {
        return normalizeLocale(systemLocale)
      }
    }

    // Method 4: Use navigator.language (for web compatibility)
    if (typeof navigator !== 'undefined' && navigator.language) {
      return normalizeLocale(navigator.language)
    }

    // Method 5: Final fallback
    return FALLBACK_DETECTED_LOCALE
  } catch (error) {
    console.error('Failed to get device locale:', error)
    return FALLBACK_DETECTED_LOCALE
  }
}

/**
 * Normalize locale string to match supported locales
 * @param locale - Raw locale string from device
 * @returns Normalized locale string
 */
function normalizeLocale(locale: string): SupportedLocale | string {
  if (!locale) return SupportedLocale.en

  // Convert to lowercase and get the language part
  const normalized = locale.toLowerCase().split(/[-_]/)[0]

  // Check if it matches our supported locales
  if (isLocaleSupported(normalized)) {
    return normalized as SupportedLocale
  }

  // Return the original locale if not supported
  return locale
}

/**
 * Check if the device locale is supported
 * @returns true if the device locale is in our supported list
 */
export function isDeviceLocaleSupported(): boolean {
  const locale = getDeviceLocale()
  return typeof locale === 'string' && isLocaleSupported(locale)
}

save locale for user

import { FALLBACK_DETECTED_LOCALE, SupportedLocale } from '@/constants/locales'
import { getDeviceLocaleWithFallback } from '@/lib/language/getDeviceLocale'
import { MMKV } from 'react-native-mmkv'

export const storage = new MMKV()

const key = 'app_locale'

export function getSavedLocale() {
  try {
    const selectedLocale = storage.getString(key)
    const deviceLocale = getDeviceLocaleWithFallback()
    // console.log('Locale info', { storedLocale: selectedLocale, deviceLocale })

    return selectedLocale || deviceLocale
  } catch {
    return FALLBACK_DETECTED_LOCALE
  }
}

export function saveLocaleToStorage(locale: SupportedLocale) {
  try {
    return storage.set(key, locale)
  } catch (err) {
    console.error('Error on store locale', locale, err)
  }
}

export function clearLocaleFromStorage() {
  try {
    return storage.delete(key)
  } catch (err) {
    console.error('Error on clear locale', err)
  }
}

Static messages

Use lingui (opens new window) library

package.json

{
  "name": "your-app",
  "main": "expo-router/entry",
  "version": "1.0.0",
  "scripts": {
    "lang:compile": "lingui compile --typescript",
    "lang:extract": "lingui extract",
    "lang:build": "npm run lang:extract && npm run lang:compile",
  },
  "dependencies": {
    "@lingui/core": "^5.3.1",
    "@lingui/react": "^5.3.1",
  }
}

lingui.config.js

import { defineConfig } from '@lingui/cli'

export default defineConfig({
  sourceLocale: 'vi',
  locales: ['vi', 'en'],
  catalogs: [
    {
      path: '<rootDir>/locales/{locale}/messages',
      include: ['app', 'components', 'modules', 'screens', 'helpers', 'constants', 'hooks', 'lib'],
    },
  ],
  format: 'po',
})

i18n.ts

import { i18n as i18nCore } from '@lingui/core'
import { messages as enMessages } from '@/locales/en/messages'
import { messages as viMessages } from '@/locales/vi/messages'

export const localeMessages = {
  [SupportedLocale.en]: enMessages,
  [SupportedLocale.vi]: viMessages,
}

// biome-ignore lint/complexity/noForEach: <explanation>
Object.values(SupportedLocale).forEach((locale) => {
  i18nCore.load(locale, localeMessages[locale])
})

export const i18n = i18nCore

app/_layout.tsx

import { I18nProvider } from '@lingui/react'

export default function RootLayout() {
  const colorScheme = useColorScheme() ?? 'light'

  return (
    <QueryClientProvider client={queryClient}>
      <ThemeColorProvider<ThemeToken, ColorSchemaName>
        colorScheme={colorScheme}
        themeModes={{
          light: lightTheme,
          dark: darkTheme,
        }}
      >
        {/* Wrap i18n provider */}
        <I18nProvider i18n={i18n} defaultComponent={Text}> 
          <SafeAreaProvider>
            <GestureHandlerRootView>
              <BottomSheetProvider>
                <RootSiblingParent>
                  <InternetConnectionBanner />
                  <InitLayout />
                </RootSiblingParent>
              </BottomSheetProvider>
            </GestureHandlerRootView>
          </SafeAreaProvider>
        </I18nProvider>
      </ThemeColorProvider>
    </QueryClientProvider>
  )
}

Single text case

import { useLingui } from '@lingui/react/macro'

function DiscountCode({ tierDiscount }: { tierDiscount: VffDiscountCode }) {
  const { t } = useLingui()
  const discountValue = displayDiscountCodeValue(tierDiscount)
  
  return (
    <Text style={[a.text_sm, a.text_white, a.font_weight_700]}>
     {t`Mã giảm giá ${discountValue}`}
    </Text>
  )
}

React nodes as children

import { Trans } from '@lingui/react/macro'

function FooterNotes() {
  return (
    <Trans>
      <Text style={[a.text_xs]}>
        Lưu ý: <Text style={[a.text_xs, a.font_weight_700]}>Mã giảm giá</Text>{' '}
        sẽ được áp dụng tại <Text style={[a.text_xs, a.font_weight_700]}>trang thanh toán của Shop</Text>{' '}
        (khi bạn được chuyển hướng từ ứng dụng). Đừng quên sao chép mã này để không bỏ lỡ ưu đãi đặc biệt dành cho bạn.
      </Text>
    </Trans>
  )
}

External packages

when user data loaded or refresh => Locale on UI should be updated if changed

export function useGetUserQuery() {
  const { i18n } = useLingui()
  const currentLocale = i18n.locale

  return useQuery({
    queryKey: ['user'],
    queryFn: async () => {
      const user = await getUser()

      if (user?.locale) {
        // handle locale on UI display
        if (user.locale !== currentLocale) {
          updateLocaleForUI(user.locale)
        }
        setAxiosDefaultLocale(user.locale)
      }
      return user
    },
  })
}

Should put content-language on request header that let backend know which locale app wants

const instance: AxiosInstance = axios.create({
  baseURL: apiUrl,
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json',
  },
})

export function setAxiosDefaultLocale(locale: string) {
  instance.defaults.headers.common['content-language'] = locale
}

export function setAxiosUserIdHeader(userId: string) {
  instance.defaults.headers.common['x-user-id'] = userId
}

import dayjs from 'dayjs'

export function updateLocaleForUI(locale: SupportedLocale | string) {
  dayjs.locale(locale)
  i18nCore.activate(locale)
}

Dynamic messages

When the backend doesn't provide a translated content for content-language in header. It's nice to have feature => The app will request to an endpoint to translate text then display for UI

Foundation

service.ts

import instance from '@/services/axios'

export type TranslationPayload = {
  content: string
  sourceLanguage?: string
  targetLanguage: string
}

export async function translateText(payload: TranslationPayload) {
  const res = await instance.post<TranslationResponse>('/translations/text', payload)
  return res.data
}

useGetTranslatedTextQuery.tsx

type Options = {
  originalLocale?: string
}

export function useGetTranslatedTextQuery(content: string, options?: Options) {
  const { 
    isKeepOriginal, 
    originalLocale, 
    targetLocale 
  } = useDetectTranslatable(options)
  const hash = hashTo32Chars(content || '')

  const result = useQuery({
    queryKey: ['translatedText', hash, targetLocale],
    enabled: !!content,
    queryFn: async () => {
      if (isKeepOriginal) {
        return content
      }
      const res = await translateText({
        content,
        targetLanguage: targetLocale,
        sourceLanguage: originalLocale,
      })
      return res.translatedContent
    },
  })

  return {
    ...result,
    isKeepOriginal,
  }
}

export function useDetectTranslatable(options?: Options) {
  const { i18n } = useLingui()
  const targetLocale = i18n.locale as SupportedLocale

  const originalLocale = options?.originalLocale || DEFAULT_CONTENT_LOCALE
  const isKeepOriginal = targetLocale === originalLocale
  return {
    translatable: !isKeepOriginal,
    isKeepOriginal,
    originalLocale,
    targetLocale,
  }
}

Simple case

TranslatedText.tsx

import { TextProps } from 'react-native'
import { useGetTranslatedTextQuery } from '../hooks/useTranslatedText'

import { Text } from '@/components/common'

type TranslatedTextProps = {
  children: string
  originalLocale?: string
} & TextProps

export function TranslatedText({ children, originalLocale, ...props }: TranslatedTextProps) {
  const { data, isLoading, isKeepOriginal } = useGetTranslatedTextQuery(children.trim(), {
    originalLocale,
  })
  if (isKeepOriginal) {
    return <Text {...props}>{children}</Text>
  }
  if (isLoading || !data) {
    return <Text {...props}>⏳ {children}</Text>
  }
  return <Text {...props}>{data}</Text>
}

<TranslatedText style={[
    a.font_weight_400,
    a.text_xs,
    a.text_dark_5,
    { lineHeight: 16 },
    ]}
>
  {label}
</TranslatedText>

Complex

TranslationContext.tsx

import React, { createContext, useContext, ReactNode } from 'react'
import { useGetTranslatedTextQuery } from '../hooks/useTranslatedText'
import { useTranslationSwitchProps } from '../hooks/useTranslationSwitchProps'
import { useGetTranslatedHtmlQuery } from '../hooks/useTranslatedHtml'

export type TranslatedContext = {
  isKeepOriginal: boolean;
  originalLocale?: string;
  originalText: string;
  displayText: string;
  translatedText?: string;
  isLoading: boolean;
  displayOriginal: boolean;
  toggleDisplayContent: () => void;
}

const TranslationContext = createContext<TranslatedContext | undefined>(undefined)

type TranslationProviderProps = {
  content: string;
  originalLocale?: string
  children: ReactNode;
}

export const TranslationProvider = ({ ...props }: TranslationProviderProps) => {
  // NOTE: could add more html provider here
  return <TranslationTextProvider {...props} />
}

function TranslationTextProvider({ content: originalText, originalLocale, children }: TranslationProviderProps) {
  const { isKeepOriginal, displayOriginal, toggleDisplayContent } = useTranslationSwitchProps({ originalLocale })

  const {
    data: translatedText,
    isLoading,
  } = useGetTranslatedTextQuery(originalText.trim(), { originalLocale })

  const value: TranslatedContext = {
    isKeepOriginal,
    originalLocale,
    originalText,
    translatedText,
    isLoading,
    displayOriginal,
    displayText: displayOriginal ? originalText : (translatedText || originalText),
    toggleDisplayContent,
  }

  return (
    <TranslationContext.Provider value={value}>
      {children}
    </TranslationContext.Provider>
  )
}

export const useTranslationContext = () => {
  const context = useContext(TranslationContext)
  if (!context) {
    throw new Error('useTranslationContext must be used within a TranslationProvider')
  }
  return context
}

TranslationRender.tsx

import { TranslatedContext, useTranslationContext } from './TranslationContext'

type DisplayContentProps = {
  render: (context: TranslatedContext) => React.ReactNode
}

export function TranslationRender({ render }: DisplayContentProps) {
  const context = useTranslationContext()
  const component = render(context)
  return <>{component}</>
}

TranslationContentSwitch.tsx

import { XStack, Text } from '@/components/common'
import { useAtoms } from '@/hooks'
import { atoms as a } from '@/themes/atoms'
import { useLingui } from '@lingui/react/macro'
import React, { ReactNode } from 'react'
import { useTranslationContext } from './TranslationContext'
import { StyleProp, TextStyle, TouchableOpacity } from 'react-native'

type ContentSwitchProps = {
  leftSection?: ReactNode;
  rightSection?: ReactNode;
  textStyle?: StyleProp<TextStyle>
}

export function TranslationContentSwitch({ leftSection, rightSection, textStyle }: ContentSwitchProps) {
  const { displayOriginal, isKeepOriginal, toggleDisplayContent } = useTranslationContext()

  if (isKeepOriginal) {
    return null
  }

  return (
    <ContentSwitchPure
      leftSection={leftSection}
      rightSection={rightSection}
      displayOriginal={displayOriginal}
      onToggle={toggleDisplayContent}
      isKeepOriginal={isKeepOriginal}
      textStyle={textStyle}
    />
  )
}

type ContentSwitchPureProps = ContentSwitchProps & {
  displayOriginal: boolean;
  onToggle: (e: any) => void;
  isKeepOriginal?: boolean;
}

export function ContentSwitchPure({
  leftSection,
  rightSection,
  displayOriginal,
  onToggle,
  isKeepOriginal = false,
  textStyle,
}: ContentSwitchPureProps) {
  const atoms = useAtoms()
  const { t } = useLingui()

  if (isKeepOriginal) {
    return null
  }

  return (
    <TouchableOpacity onPress={onToggle}>
      <XStack>
        {leftSection}
        <Text style={[a.font_weight_400, a.text_xs, atoms.text_info, textStyle]}>
          {displayOriginal ? t`Xem bản dịch` : t`Xem bản gốc`}
        </Text>
        {rightSection}
      </XStack>
    </TouchableOpacity>
  )
}

function TextDisplay({ post }: { post: Amity.Post }) {
  const { text_secondary_high, text_tertiary_high } = useAtoms()
  const bottomSheet = useBottomSheet()

  const dataText = (post.data as Amity.ContentDataText).text

  return (
    <TranslationProvider content={dataText}>
      <TranslationRender render={({ displayText }) => (
        <Pressable onPress={() => {
          bottomSheet.expand({
            enableDynamicSizing: false,
            snapPoints: ['50%'],
            children: <BottomSheetContent post={post} content={displayText} />,
          })
        }}
        >
          <Text numberOfLines={2} style={[text_secondary_high, a.text_sm]}>
            {(displayText).replace(/\n/g, ' ')}
          </Text>
        </Pressable>
      )}
      />

      <TranslationContentSwitch textStyle={[text_tertiary_high]} />
    </TranslationProvider>
  )
}