Guide to Working with Translations (react-intl)

The project uses the react-intl library to manage multilingual content. This guide describes the basic operations with translations.

Adding a New Translation

1. Add a new message to the translations definition file:

// Translations definitions file (*.intl.js)
import { defineMessages } from 'react-intl';

const messages = defineMessages({
  // Existing translations...

  // New translation
  accessClosed: {
    id: 'AccessClosed.accessClosed',     // Unique message identifier
    defaultMessage: 'Access closed',      // Default language text (English)
    description: 'Access closed message', // Description for translators
  },
});

export default messages;

2. Extract new messages for translation:

yarn run extract-intl

After running this command, the new message will be automatically added to all localization files in the /lang/*.json directory.

Updating an Existing Translation

When you need to change an existing translation (e.g., fixing a typo or changing wording), follow these steps:

1. Update the message in the translations definition file (messages.js)
2. Update the translation in /lang/en.json (primary language)
3. Clear outdated translations in other language files:
   • For all non-English language files (/lang/*.json except /lang/en.json), you need to replace the old translation value with an empty string ("") for the affected key
   • This ensures translators will notice that the translation needs to be updated
   • Important: Do NOT delete the key entirely - just empty the value

Using the Helper Script

To automate step 3, you can use the provided script:

1. Open scripts/translations/remove-messages-by-key.js
2. Add the translation keys you want to clear to the messagesKeysForRemove array:

   const messagesKeysForRemove = [
     "editVehicle.totalKmIncluded",
     "dashboard.welcomeMessage"
   ];

3. Run the script:

   node scripts/translations/remove-messages-by-key.js

4. The script will automatically set these translations to empty strings in all language files except en.json

Example

If you’re updating the message with key "dashboard.welcomeMessage":

• Before in /lang/fr.json: "dashboard.welcomeMessage": "Bienvenue"
• After in /lang/fr.json: "dashboard.welcomeMessage": ""

Deleting a Translation

1. Remove the message from the translations definition file (messages.js)
2. Remove the corresponding entries from all localization files /lang/*.json

Using Translations in Components

import React from 'react';
import { FormattedMessage } from 'react-intl';
import messages from './messages.intl';

const MyComponent = () => (
  <div>
    <FormattedMessage {...messages.accessClosed} />
  </div>
);

export default MyComponent;

Using the useIntl Hook

import React from 'react';
import { useIntl } from 'react-intl';
import messages from './messages.intl';

const MyComponent = () => {
  const intl = useIntl();

  // Simple string translation
  const translatedText = intl.formatMessage(messages.accessClosed);

  // Translation with parameters
  const welcomeMessage = intl.formatMessage(
    messages.welcome,
    { name: 'User' }
  );

  // Usage in event handlers
  const handleClick = () => {
    alert(intl.formatMessage(messages.clickAlert));
  };

  return (
    <div>
      <p>{translatedText}</p>
      <p>{welcomeMessage}</p>
      <button onClick={handleClick}>Click me</button>
    </div>
  );
};

export default MyComponent;

Additional Recommendations

• Use meaningful identifiers for messages
• Always add clear descriptions for translators
• Regularly synchronize translations with the locale editor