Translating OpenMarch

OpenMarch uses Tolgee for internationalization (i18n), which provides in-context translation editing and makes it easy to manage translations across multiple languages.

Current Languages

OpenMarch currently supports the following languages:

• English (en)
• Spanish (es)
• French (fr)
• Portuguese (Brazil) (pt-BR)
• Japanese (ja)

Translation files are located in apps/desktop/i18n/. Translators do not need to edit these files directly. Use Tolgee’s web interface or in-context translation features instead.

---

For Translators (Non-Coders)

This section is for people who want to contribute translations without writing code.

There are two ways to add translations:

1. Using Tolgee’s web interface
2. In-context translation directly in the OpenMarch app

For both methods, you’ll need to create a Tolgee account and get access to the OpenMarch project.

Get Access to the OpenMarch Tolgee Project

You can use one of two methods to get access:

• Request access via email: Contact the OpenMarch team at contact@openmarch.com. Use the subject line “Tolgee Access Request” and tell us what languages you want to help translate.
• Send a Discord message: Join the OpenMarch Discord server and send a message in the #translation-and-localization channel requesting access to the Tolgee project.

After a quick chat, we’ll send you a link to join the Tolgee project. Following the link, you may need to create a Tolgee account if you don’t have one already.

Getting Started with In-Context Translation

In-context translation allows you to edit translations directly within the OpenMarch app, making it easier to see where text appears.

Step 1: Get a Tolgee API Key

1. Go to app.tolgee.io
2. In the top-right corner, click your profile icon and select Project API keys
3. Click the ”+ API Key” button and select the OpenMarch project. Name it as you’d like and set the expiration date (we recommend 30 days). You can leave the default permissions as they are.
4. Save the key and copy the generated API key to your clipboard. You can’t see it again later, so make sure to copy it now.

Step 2: Enable Developer Settings

1. Open OpenMarch
2. Go to App Settings
3. Expand the Developer Settings section
4. Toggle on Tolgee In-Context Translating
5. Paste your API key into the text field

Step 3: Start Translating

After enabling Tolgee, you can immediately start translating directly in the app:

1. Press Alt (or Option on Mac) to see translation keys highlighted when hovering over text
2. Click on any highlighted text to edit the translation
3. Use the Tolgee UI to add translations in different languages.
4. Mark translations as “Reviewed” when you’re done
5. Changes are saved to the Tolgee cloud when you click “Update”

Translation Tips for Non-Coders

• Context matters: When translating, consider where the text appears in the app
• Keep it concise: Try to match the length of the original text when possible to avoid layout issues
• Test different languages: Switch between languages in the app to see how your translations look
• Ask questions: If you’re unsure about context or meaning, send a message in Discord or email the OpenMarch team, we’re happy to help!

Troubleshooting for Translators

Translations not showing up

• Make sure you’ve saved your changes in the Tolgee UI
• Refresh the app after adding translations
• Check that you’re viewing the correct language in the app settings

In-context editing not working

• Verify your API key has the correct permissions
• Make sure Tolgee In-Context Translating is enabled in App Settings → Developer Settings
• Refresh the app after enabling Tolgee In-Context Translating
• Try pressing Alt to toggle the Tolgee UI

---

For Developers (Programmers)

This section is for developers who need to make new text translatable in the codebase.

Important: As a developer, you don’t need to use Tolgee API keys or interact with Tolgee directly. You only need to:

1. Add translation keys to your code
2. Manually update the English translation file (apps/desktop/i18n/en.json) with the new keys and English text
3. Commit your changes

The OpenMarch team will upload new keys to Tolgee, where translators can add translations for other languages.

Adding Translations in Code

When writing new features, you need to add translatable strings to your components using translation keys.

Using the <T> Component

For simple text translations:

import { T } from "@tolgee/react";

export function MyComponent() {
  return (
    <div>
      <h1>
        <T keyName="myFeature.title" />
      </h1>
      <p>
        <T keyName="myFeature.description" />
      </p>
    </div>
  );
}

Using the Translation Hook

For translations in JavaScript logic or with parameters:

import { useTranslate } from "@tolgee/react";

export function MyComponent() {
  const { t } = useTranslate();

  const errorMessage = t("myFeature.error");
  const greeting = t("myFeature.greeting", { name: "User" });

  return <div>{greeting}</div>;
}

Translations with Parameters

For dynamic content, use parameters:

<T
  keyName="settings.plugins.toast.installSuccess"
  params={{ pluginName: "My Plugin" }}
/>

In the translation file, use the parameter like this:

{
  "settings": {
    "plugins": {
      "toast": {
        "installSuccess": "Plugin {pluginName} installed successfully!"
      }
    }
  }
}

Translations with Rich Text

For translations containing HTML elements:

<T
  keyName="settings.plugins.refreshNotice"
  params={{
    a: (content) => (
      <strong
        className="cursor-pointer"
        onClick={() => window.location.reload()}
      >
        {content}
      </strong>
    ),
  }}
/>

In the translation file:

{
  "settings": {
    "plugins": {
      "refreshNotice": "Please <a>refresh</a> the app to apply changes"
    }
  }
}

Adding Keys to the English Translation File

After adding translation keys to your code, you must manually add them to the English translation file:

1. Open apps/desktop/i18n/en.json

2. Add your new keys with their English text following the existing structure (see Translation File Structure below)

3. Ensure keys are alphabetically sorted (or follow the existing organization pattern)

4. Save the file

Do not edit other language files (es.json, fr.json, etc.) - the OpenMarch team will upload new keys to Tolgee, where translators will provide translations for other languages. These translations will be synced back to the repository periodically.

Commit Your Changes

After adding translation keys to your code and updating en.json, commit your changes:

git add apps/desktop/i18n/en.json
git add [your code files]
git commit -m "Add translations for new feature"

Translation File Structure

Translation files are organized by language code in apps/desktop/i18n/:

apps/desktop/i18n/
├── en.json      # English (default)
├── es.json      # Spanish
├── fr.json      # French
├── pt-BR.json   # Portuguese (Brazil)
└── ja.json      # Japanese

Each file contains a nested JSON structure organized by feature or section:

{
  "settings": {
    "developer": "Developer Settings",
    "tolgeeDevToolsToggle": "Tolgee In-Context Translating",
    "tolgeeApiKeyPlaceholder": "Enter your Tolgee API key",
    "plugins": {
      "refreshNotice": "Please <a>refresh</a> the app to apply changes"
    }
  },
  "actions": {
    "alignment": {
      "alignHorizontally": "Align horizontally",
      "distributeVertically": "Evenly distribute marchers vertically"
    }
  }
}

When using translation keys in your code, reference them with dot notation: settings.developer, settings.plugins.refreshNotice, actions.alignment.alignHorizontally.

Best Practices for Developers

Key Naming Conventions

• Use dot notation for hierarchical organization: section.subsection.key
• Use descriptive names that indicate where the text appears: settings.plugins.install
• Keep keys lowercase with camelCase for the last segment

Writing Translatable Content

• Keep strings concise and context-free when possible
• Avoid concatenating strings (use parameters instead)
• Don’t hardcode text that will be displayed to users
• Consider plural forms and gender when relevant

Testing Translations

1. Enable DevTools and switch between languages in the app
2. Check that all UI elements display properly in different languages
3. Verify that text doesn’t overflow containers
4. Test with longer languages (French, Portuguese) to ensure layout flexibility

Troubleshooting for Developers

Translations not showing up

• Verify the translation key matches exactly (case-sensitive)
• Check that the key exists in en.json with the correct English text
• Ensure the language file is imported in Tolgee.ts
• Restart the app after adding new translations

Translation key not found errors

• Check that the key exists in en.json (the default language)
• Verify there are no typos in the key name in your code
• Make sure you’ve committed the updated en.json file

---

Resources

• Tolgee Documentation
• Tolgee React Integration
• OpenMarch Translation Files