Usage

This section will guide you through using TranslateSheet in your project, including defining translations, generating translation files, and integrating with i18next.

Defining Translations

With TranslateSheet, you can define translations directly within your components during development. Here’s an example:

import TranslateSheet from "translate-sheet";
 
export default function ExampleComponent() {
  return (
    <div>
      <p>{translations.greeting}</p>
      <p>{translations.welcomeMessage({ name: "Olivia" })}</p>
    </div>
  );
}
 
const translations = TranslateSheet.create("example-namespace", {
  greeting: "Hello!",
  welcomeMessage: "Welcome, {{name}}!",
});

The above example will return the following output:

• TranslateSheet.create(namespace, translations) dynamically registers a namespace and the corresponding translations.
• Translations can be static strings or interpolated strings.
• During development, translations are read from the local TranslateSheet object, enabling you to see your changes in real time.

Interpolation

TranslateSheet supports dynamic interpolation using placeholders within your translation strings. Interpolation allows you to insert variables directly into your strings.

function Profile({ name }) {
  return <p>{translations.welcomeMessage({ name })}</p>;
}
 
const translations = TranslateSheet.create("profile", {
  welcomeMessage: "Hello, {{name}}!",
});

In this example, {{name}} is replaced with the provided value when translations.welcomeMessage is called.

Generating Translation Files

Once you’ve defined your translations, run the following command to generate the consolidated translation files:

npx translate-sheet generate

yarn translate-sheet generate

bun translate-sheet generate

This command will:

1. Extract all TranslateSheet objects from your codebase.
2. Generate translation files for the target languages specified in your translateSheetConfig.js.
3. Upload all of your apps translations to the TranslateSheet backend for easy access and management in the dashboard.

Example Output

If your primaryLanguage is en, the output file might look like this if you have a target language set to es:

// es.ts
 
const es = {
 "sign-in": {
    signIn: "Iniciar sesión",
    password: "Contraseña",
    phoneNumber: "Número de teléfono",
    sendCode: "Enviar código: {{copy1}}",
  },
  profile: {
    title: "Perfil",
    edit: "Editar",
    signOut: "Cerrar sesión",
    username: "Nombre de usuario",
    name: "Nombre",
    update: "Actualizar",
    deleteAccount: "Eliminar cuenta",
  },
};
 
export default es;

Managing and Updating Translations

To keep your app’s translations up to date, avoid editing any translation files locally. Instead, make all updates directly in the TranslateSheet dashboard.

1. Access the dashboard: Head to the dashboard to view, edit, or add translations for different languages.
2. Apply changes: Once you’ve made the necessary edits, you’ll be ready to sync them with your project.

To fetch the latest translations, run:

npx translate-sheet pull

yarn translate-sheet pull

bun translate-sheet pull

This command retrieves the updated translations from the TranslateSheet backend and updates your local files accordingly. This ensures that your translations are always in sync without the risk of manual conflicts or outdated entries.

Uploading Existing Translations

For instances where you want to adopt TranslateSheet and already have your own translation files, TranslateSheet allows you to upload your existing files from your project to the TranslateSheet dashboard. This process ensures that all of your preexisting translation content—including your primary language—is synchronized with the backend for centralized management.

To upload your existing translations, run the following command:

npx translate-sheet push

yarn translate-sheet push

bun translate-sheet push

This command uploads all of your existing translation files to the TranslateSheet backend, enabling you to manage and update your translations directly from the dashboard.

Integrating with i18next

TranslateSheet works alongside i18next to manage runtime translations. After generating your consolidated translation files using the generate command, TranslateSheet will automatically create a resources file containing all of your translations.

You can integrate the generated resources file into your i18next setup like this:

import i18n from "i18next";
import resources from "./resources";
 
await i18n.init({
  resources,
  lng: "en",
  fallbackLng: "en",
});

This setup ensures that your app can dynamically load the appropriate translations at runtime without needing to manually import each language file.

• resources: This object, automatically generated by TranslateSheet, contains translations for each generated language.
• lng: Specifies the initial language.
• fallbackLng: Provides a fallback language if the current language is unavailable.

For further information on integrating with i18next, refer to the official documentation .

Language Detection

TranslateSheet uses i18next for runtime translations. By default, it automatically detects the user’s device language and loads the corresponding translation file.

To manually set the language, use:

import i18n from "i18next";
 
i18n.changeLanguage("es"); // Change language to Spanish

Next Steps

You now have a basic understanding of how to use TranslateSheet. For general questions, head over to the FAQ section.