LinguFox

Installation

1. Create a LinguFox account

• Visit LinguFox and create an account
• Create a Web App via the "Onboarding Process" or later using the "Add new Web App" button
• Once successfully created, you will receive a Web App token

2. Configure Web App

2.1. Install The Package

npm install @lingufox/client
# or 
yarn add @lingufox/client

2.2 Initialization

It is necessary to initialize library in the root file (main.ts, index.ts...), before starting the React app as in example shown bellow

Init Function

import { init, LanguageCode } from '@lingufox/client'

init({
    code: '6gmhja7xN03MhCZ7HcBTaIeUddZ7pRSGwTCex99.dGVuYW50X1lGYTRRanRrcmRfMzUwMDQw',
    clientTranslations: defaultTranslation,
    defaultLanguage: LanguageCode.EN,
})

Configuration Options

| Option | Required | Description | | ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | | code | yes | A unique code for connecting client applications to the LinguFox. | | clientTranslations | yes | Translation resources | | defaultLanguage | yes | The base language of your application. Must match the Source Language selected in LinguFox. This language serves as the foundation for all translations. Note: Source Language cannot be changed in LinguFox once created - you would need to create a new application if a different source language is required. | | supportedLngs | no | An array of allowed languages | | enableDebugMode | no | Enable debug log on the console |

3. Verify the Connection

After implementing LinguFox in your application, verify the connection by:

• Opening your Web App in a new tab to trigger the connection status update
• OR go to your Web App detail page inside LinguFox and clicking the refresh icon

NOTE: When clicking the refresh icon from the Web App detail page inside the LinguFox, you will see a popup confirming that the library is installed and successfully connected.

Initialization Example

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import './index.css'
import { init, TranslationResource, LanguageCode } from '@lingufox/client'

const defaultTranslation: TranslationResource = {
    [LanguageCode.EN]: {
        translation: {
            'test-key-1': 'This is a default translation for the key',
            'test-key-2': 'This is a default translation for the key 2',
            'test-key-11': 'This is a default translation for the key 11',
            'test-key-111': 'This is a default translation for the key 111',
            'test-key-intrapolation':
                'This is a default translation for the key {{key}}',
        },
    },
    [LanguageCode.DE]: {
        translation: {
            'test-key-1': 'Dies ist eine Standardübersetzung für den Schlüssel',
            'test-key-2':
                'Dies ist eine Standardübersetzung für den Schlüssel 2',
            'test-key-11':
                'Dies ist eine Standardübersetzung für den Schlüssel 11',
            'test-key-111':
                'Dies ist eine Standardübersetzung für den Schlüssel 111',
            'test-key-intrapolation':
                'Dies ist eine Standardübersetzung für den Schlüssel {{key}}',
        },
    },
}

init({
    code: '6gmhja7xN03MhCZ7HcBTaIeUddZ7pRSGwTCex99.dGVuYW50X1lGYTRRanRrcmRfMzUwMDQw',
    clientTranslations: defaultTranslation,
    defaultLanguage: LanguageCode.EN,
    supportedLngs: [LanguageCode.EN, LanguageCode.DE],
}).then(() => {
    ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
        <React.StrictMode>
            <App />
        </React.StrictMode>
    )
})

Default Translations

Default translations need to be set for the default language and can also be set for other languages used in the application. They serve two key purposes:

1. They provide a starting point for translating a key.
2. They act as a fallback value if a key is not translated or if the application data is unavailable.

const defaultTranslation: TranslationResource = {
    [LanguageCode.EN]: { // For example the default language here is English
        translation: {
            'test-key-1': 'This is a default translation for the key',
            'test-key-2': 'This is a default translation for the key 2',
            'test-key-11': 'This is a default translation for the key 11',
            'test-key-111': 'This is a default translation for the key 111',
            'test-key-intrapolation':
                'This is a default translation for the key {{key}}',
        },
    },
}

Translation Function

You can add localized text keys using the Translate component and the useTranslation hook. Here are examples of both:

import './App.css'
import { useTranslate, Trans } from '@lingufox/client'

function App() {
    const { t } = useTranslation()

    return (
        <div>
            <h1> Test React Vite App </h1>
            Component: <Trans
                i18nKey="test-key-1"
                components={{
                    u: <u />,
                    em: <em />,
                    a: <a />,
                }}
            />
            Translatable:{' '}
            <Trans
                i18nKey="test-key-translatable"
                components={{
                    u: <u />,
                    em: <em />,
                    a: <a />,
                }}
            />
            <div></div>
            <p> {t('test-key-10')} </p>
            <p> {t('test-key-11')} </p>
            <p> {t('test-key-12')} </p>
            <p> {t('test-key-intrapolation', { key: 1 })} </p>
            <div></div>
        </div>
    )
}

export default App

Changing Language

To change the localization, use the changeLanguage function. Here’s an example:

import { useTranslate, LanguageCode } from '@lingufox/client'
const { t } = useTranslate()

changeLanguage(LanguageCode.DE)

By following these steps, you can effectively integrate and utilize the LinguFox library in your React application.

Best Practices

1. String Concatenation

Avoid string concatenation in translations as it can lead to issues with word order in different languages.

❌ Don't do this:

`${t(translationSourceLanguageIso)} (${t('source_language')})`
// or
t(translationSourceLanguageIso) + ' (' + t('source_language') + ')'

✅ Do this instead:

// In translation file:
{
    "source_language_iso": "{{sourceLanguage}} (Source Language)"
}

// In your code:
t('source_language_iso', {
    sourceLanguage: t(translationSourceLanguageIso)
})

These best practices are aligned with i18next's recommended best practices to ensure consistent and maintainable localization patterns.