Back to Plugins

Tolgee Localization Plugin

Integrate Tolgee's powerful translation management platform with Medusa to easily add multilingual support to your e-commerce store.

Overview

This plugin connects Medusa V2 with Tolgee, an open-source localization platform, enabling seamless translation management for your product data without the complexity of traditional CMS systems. Manage translations in-context, leverage AI-powered suggestions, and collaborate with your team on multilingual content.

Features

Supported Models

The plugin supports translation for:

Requirements

Installation

Install the plugin using npm:

npm install medusa-plugin-tolgee

Configuration

Step 1: Set Up Tolgee

  1. Create a free account at tolgee.io
  2. Create a new project for your Medusa store
  3. Generate an API key with appropriate permissions
  4. Note your Tolgee API URL

Step 2: Environment Variables

Add Tolgee credentials to your .env file:

TOLGEE_API_URL=https://app.tolgee.io
TOLGEE_API_KEY=your_tolgee_api_key
TOLGEE_PROJECT_ID=your_project_id

Step 3: Plugin Configuration

Add the plugin to your medusa-config.js:

const plugins = [
  // ... other plugins
  {
    resolve: "medusa-plugin-tolgee",
    options: {
      api_url: process.env.TOLGEE_API_URL,
      api_key: process.env.TOLGEE_API_KEY,
      project_id: process.env.TOLGEE_PROJECT_ID,
      // Optional: Default language
      default_language: "en",
      // Optional: Custom attributes to translate
      custom_attributes: {
        product: ["meta_title", "meta_description"],
      },
    },
  },
]

Step 4: Sync Models

After installation, sync your Medusa models with Tolgee through the admin panel:

  1. Log into Medusa admin
  2. Navigate to the Tolgee section
  3. Click “Sync Models”
  4. Wait for synchronization to complete

Usage

Admin Panel

Translation Management Widget

The plugin adds a translation widget to the Medusa admin:

  1. View Translations - See all translations for a model
  2. Edit Translations - Update translations directly
  3. Add Languages - Add new language support
  4. Sync Status - View synchronization status

Managing Translations

  1. Navigate to a product, collection, or category
  2. Open the Tolgee translation widget
  3. Select target language
  4. Edit translations
  5. Save changes

Automatic Synchronization

The plugin automatically syncs with Tolgee when:

Frontend Integration

Using Medusa SDK

Access translated content through linked properties:

import { sdk } from "@medusajs/medusa"

// Fetch product with translations
const product = await sdk.store.product.retrieve(productId, {
  fields: "+translations.*",
})

// Access translated title
const translatedTitle = product.translations.find(
  t => t.language_code === "es"
)?.title || product.title

Using Tolgee React Hook

For in-context translation on the frontend:

import { T } from "@tolgee/react"

function ProductTitle({ product }) {
  return (
    <h1>
      <T keyName={`product.${product.id}.title`}>
        {product.title}
      </T>
    </h1>
  )
}

AI-Powered Translation

Automatic Translation Suggestions

Enable AI translation in Tolgee:

  1. Configure translation provider (DeepL, Google, or AWS)
  2. Add API credentials in Tolgee dashboard
  3. Use “Auto-translate” feature for suggestions

Translation Providers

DeepL

Google Translate

AWS Translate

Collaborative Translation

Team Workflows

  1. Translators - Add and edit translations
  2. Reviewers - Review and approve translations
  3. Approvers - Final approval before publishing

Review Process

  1. Translator submits translation
  2. Reviewer checks translation quality
  3. Reviewer approves or requests changes
  4. Translation goes live after approval

Custom Attributes

Translate custom fields in your models:

{
  resolve: "medusa-plugin-tolgee",
  options: {
    // ... other options
    custom_attributes: {
      product: [
        "meta_title",
        "meta_description",
        "seo_keywords",
        "specifications",
      ],
      product_variant: [
        "color_name",
        "size_name",
      ],
      collection: [
        "banner_text",
        "meta_title",
      ],
    },
  },
}

Languages

Adding Languages

  1. In Tolgee Dashboard:

    • Navigate to Languages
    • Click “Add Language”
    • Select language code (e.g., es, fr, de)
    • Save

  2. Sync with Medusa:

    • New language automatically available
    • Start translating content

Language Codes

Use standard ISO language codes:

Translation States

Track translation progress:

Best Practices

  1. Consistent Naming - Use consistent key names for translations
  2. Context - Provide context for translators
  3. Review Process - Always review translations before publishing
  4. AI as Assistant - Use AI for suggestions, not final translations
  5. Regular Sync - Keep Tolgee and Medusa synchronized
  6. Backup - Export translations regularly
  7. Testing - Test translations in staging environment

Use Cases

Global E-commerce

Multi-Regional Stores

Content Management

Performance

Caching

The plugin caches translations for performance:

Optimization

Best practices for performance:

Links

See all guides

Explore More Medusa Plugins

Find more powerful plugins and integrations to enhance your Medusa store. Browse our collection of community-driven solutions.

Browse All Plugins Submit Your Plugin
Free & Open Source
Community Driven
Easy Integration