useTs

React hook that provides the ts function for translating messages in your React Native application.

import { useTs } from '@terai/react-native'
import { View, Text } from 'react-native'

function Component() {
  const { ts } = useTs()

  return <Text>{ts`Hello, world!`}</Text>
}

Return Value

Returns an object containing:

ts

• Type: (strings: TemplateStringsArray, ...values: any[]) => string

The translation function that uses tagged template literals to translate messages. It automatically:

• Extracts the message and normalizes it
• Looks up the translation in the loaded dictionary
• Interpolates any variables passed in the template

Example:

import { View, Text, Button } from 'react-native'
import { useTs } from '@terai/react-native'

function MyComponent() {
  const { ts } = useTs()

  // Simple translation
  const greeting = ts`Hello, world!`

  // With variables
  const name = 'John'
  const personalGreeting = ts`Hello, ${name}!`

  // With expressions
  const count = 5
  const message = ts`You have ${count} new messages`

  return (
    <View>
      <Text>{greeting}</Text>
      <Text>{personalGreeting}</Text>
      <Text>{message}</Text>
    </View>
  )
}

Options

chunkId

• Type: string | undefined
• Default: undefined

Optional identifier for code-splitting translations into chunks. When provided, loads only the specific chunk of translations needed for this component.

const { ts } = useTs({ chunkId: 'dashboard' })

This enables:

• Smaller bundle sizes: Load only translations needed for specific features
• Faster initial load: Defer loading translations for screens not yet visited
• Better code organization: Group translations by feature/screen

Example with code splitting:

// Dashboard screen only loads dashboard translations
function DashboardScreen() {
  const { ts } = useTs({ chunkId: 'dashboard' })

  return <Text>{ts`Dashboard Overview`}</Text>
}

// Settings screen only loads settings translations
function SettingsScreen() {
  const { ts } = useTs({ chunkId: 'settings' })

  return <Text>{ts`User Settings`}</Text>
}

Behavior

Suspense Mode

The hook's behavior depends on the suspense configuration in setupTerai:

When suspense: true (requires React Suspense boundary):

• Component suspends while dictionary loads on first access
• Subsequent renders with cached dictionaries are instant (no suspension)
• Ideal for apps using Suspense boundaries

When suspense: false (default):

• Returns empty dictionary while loading
• Component re-renders when dictionary is ready
• No Suspense boundary required

Performance Optimization

The hook is optimized for instant locale switching:

• If dictionary exists in cache (AsyncStorage or previous load): instant return
• Only suspends/loads on first access to a locale/chunk combination
• Locale changes are instant when dictionaries are already cached

Requirements

• Must be called inside a React component
• Requires setupTerai to be called first
• Requires @react-native-async-storage/async-storage to be installed
• If suspense: true, component must be wrapped in a <Suspense> boundary

import { Suspense } from 'react'
import { Text } from 'react-native'

function App() {
  return (
    <Suspense fallback={<Text>Loading translations...</Text>}>
      <MyComponent />
    </Suspense>
  )
}

React Native Specific Notes

• Works seamlessly with React Native's navigation libraries (React Navigation, etc.)
• Integrates with React Native's Suspense for optimal loading states
• Translations persist across app restarts via AsyncStorage
• No flash of untranslated content on app launch