Medusa Multilingual Tolgee Plugin

About the plugin

The Medusa Tolgee Multilingual Plugin integrates Medusa eCommerce with Tolgee, an open-source localization platform, to offer an effortless translation management solution.

Designed with simplicity in mind, this plugin streamlines the translation of product data without the need for complex CMS or PIM systems. By harnessing the power of Tolgee, users access powerful localization features directly within their Medusa admin panel.

In this article, we will delve into how to use the plugin, walking you through its key features.

Key Features of Tolgee

• In-Context Translating: Utilize Tolgee’s development tools to translate content directly on the frontend, providing a real-time, intuitive translating experience.
• Translation Assistance: Enhance translation accuracy and speed with automatic translation suggestions powered by leading AI services such as DeepL, Google Translate, and AWS Translate.
• Collaborative Workflows: Streamline the translation process with features that support collaboration, allowing teams to easily review and approve translations, ensuring consistency and quality.

Tolgee is all about making the translation process as simple as possible. For more details on the extensive capabilities of Tolgee, visit their official website: Tolgee.io.

Plugin Features

How to Use?

Set up your Tolgee project

Before configuring the Medusa plugin, ensure your Tolgee project is ready. You can either set up an open-source version of Tolgee on your own infrastructure or opt for the managed cloud version offered by Tolgee. Obtain your project ID from the project's dashboard URL (e.g., https://app.tolgee.io/projects/YOUR_PROJECT_ID).

Install the plugin

npm install medusa-multilingual-tolgee

or

yarn add medusa-mulitilingual-tolgee

Add plugin configurations to medusa-config.js

Once your Tolgee project is set up, add the plugin configuration to your Medusa store by modifying the medusa-config.js file. Here's what you need to include:

const plugins = [
  {
    resolve: `medusa-multilingual-tolgee`,
    options: {
      baseURL: process.env.MEDUSA_ADMIN_TOLGEE_API_URL,
      apiKey: process.env.MEDUSA_ADMIN_TOLGEE_API_KEY,
      defaultLanguage: "en",
      availableLanguages: [
        { label: "English", tag: "en" },
        { label: "German", tag: "de" },
        { label: "Polish", tag: "pl" },
      ],
      productsKeys: ["title", "subtitle", "description"],
      projectId: "your_tolgee_project_id",
      enableUI: true,
    },
  },
];

Configuration options:

• defaultLanguage: This is the default language for your translations. By default, set to "en" for English, but it can be adjusted based on your primary audience.
• availableLanguages: This array contains objects defining the languages you want to support. Each object should have a label, which is the display name of the language, and a tag, which is the language code (as defined in your Tolgee project). Make sure these tags match the language tags in your Tolgee project.
• productsKeys: Specify which properties of the Medusa product data should be translatable. Common keys include "title", "subtitle", and "description", but you can specify any other fields you need translated.
• projectId: Your Tolgee project ID, which you can find in the URL of your project dashboard on the Tolgee platform.
• enableUI: Set this to true to enable the translation management UI components within the Medusa admin. This will allow users to manage translations directly from the Medusa admin panel.

Set Environment Variables in Medusa

MEDUSA_ADMIN_TOLGEE_API_URL=your_tolgee_app_url
MEDUSA_ADMIN_TOLGEE_API_KEY=your_tolgee_api_key

Explanation of Variables

• MEDUSA_ADMIN_TOLGEE_API_URL: This is the base URL where your Tolgee instance is hosted. If you are using the Tolgee cloud service, this will be https://app.tolgee.io. If you have a self-hosted instance, replace this URL with the URL of your own deployment.
• MEDUSA_ADMIN_TOLGEE_API_KEY: You can find or generate a new API key by navigating to /account/apiKeys within your Tolgee dashboard. If you haven't generated an API key yet, create one by following the prompts in the Tolgee interface.

Sync all your products with Tolgee

After configuring your environment variables and setting up the plugin, it's time to synchronize your product data with Tolgee to enable translations across your eCommerce platform. Here's how to complete the synchronization process and start translating your products:

Restart Medusa: First, ensure that all your changes are saved, then restart your Medusa server to apply the new configuration settings. This ensures that all components are loaded correctly, including the newly configured translation management plugin.

Access the Translation Management Section: Navigate to the product edit page within your Medusa admin panel. Here's what you need to do:

Scroll to the Translation Management Section: On the product edit page, scroll down until you find a new section labeled "Translation Management". This section is added by the medusa-multilingual-tolgee plugin and provides the tools necessary for managing product translations.

Initiate the Sync Process: Click on the "Sync all translations" button within the Translation Management section. This action triggers a batch job that communicates with Tolgee to create translations for existing products.

Wait for Completion: After clicking the sync button, the process may take some time depending on the number of products and the complexity of the translations.

How to Use It on the Frontend?

• Next.js Pages Router: Tolgee Pages Router

• Next.js App Router: Tolgee App Router

• Step-by-step guide of using it with Medusa storefront: Coming soon

Final Steps

Congratulations! Your configuration is now complete, and you can start translating all of your products. 🎉

If you want to translate a word, press the ALT button and click on the word in the Value column.

And if you have any questions, need help with installing or configuring the plugin, or require assistance with your Medusa project—we are here to help! Contact us!