Tolgee Localization Plugin (HiCity)

Add comprehensive multilingual support to Medusa V2 with Tolgee's translation management platform, maintained by Allen Cao.

Overview

This plugin integrates Tolgee, an open-source localization management platform, with Medusa V2 e-commerce stores. It provides in-context translation functionality, AI-powered translation suggestions, and collaborative team workflows for managing multilingual content.

Features

• Tolgee Integration - Seamless connection with Tolgee platform
• In-Context Translation - Translate content directly on the frontend with live preview
• AI-Powered Suggestions - Automatic translations via:
  • DeepL
  • Google Translate
  • AWS Translate
• Team Collaboration - Review and approval workflows for translations
• Admin Widget - Translation management directly in Medusa admin
• Auto-Sync - Automatic synchronization when models change
• Custom Attributes - Support for custom model fields
• Multiple Entity Types - Translate various Medusa models
• MedusaJS v2 Compatible - Built for Medusa V2

Supported Models

Translate content across multiple Medusa models:

• Products - Product titles and descriptions
• Product Variants - Variant names and details
• Product Options - Option names and values
• Collections - Collection titles and descriptions
• Categories - Category names and descriptions
• Product Types - Type names
• Tags - Tag values
• Shipping Options - Shipping method names

Requirements

• MedusaJS v2
• Node.js (latest LTS recommended)
• Tolgee account
• Tolgee API credentials

Installation

Install the plugin using npm:

npm install @hicity/medusa-plugin-tolgee

Configuration

Step 1: Create Tolgee Account

1. Sign up at tolgee.io
2. Create a new project
3. Generate API key
4. Note your API URL and project ID

Step 2: Environment Variables

Add to your .env file:

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

Step 3: Plugin Configuration

Add to your medusa-config.js:

const plugins = [
  // ... other plugins
  {
    resolve: "@hicity/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,
      default_language: "en",
      // Optional: Specify custom attributes to translate
      custom_attributes: {
        product: ["meta_title", "meta_description"],
        collection: ["banner_text"],
      },
    },
  },
]

Usage

Admin Panel Management

Translation Widget

Access the translation widget in Medusa admin:

1. Navigate to any supported model (product, collection, etc.)
2. Open the Tolgee translation widget
3. View and edit translations for all languages
4. Save changes to sync with Tolgee

Syncing Models

Initial sync and updates:

1. Go to Tolgee settings in admin
2. Click “Sync Models”
3. All supported models sync to Tolgee
4. Future changes auto-sync

Frontend Integration

Medusa SDK

Access translations through the Medusa SDK:

// Fetch product with translations
const product = await medusa.products.retrieve(productId, {
  expand: "translations",
})

// Get translation for specific language
const translation = product.translations.find(
  t => t.language_code === "fr"
)

const translatedTitle = translation?.title || product.title

Tolgee React Hooks

For in-context translation:

import { T, useTranslate } from "@tolgee/react"

function ProductCard({ product }) {
  const { t } = useTranslate()

  return (
    <div>
      <h2>
        <T keyName={`product.${product.id}.title`}>
          {product.title}
        </T>
      </h2>
      <p>{t(`product.${product.id}.description`)}</p>
    </div>
  )
}

AI-Powered Translation

Setup Translation Providers

Configure in Tolgee dashboard:

1. DeepL

   • Add DeepL API key
   • High-quality translations
   • Best for European languages

2. Google Translate

   • Add Google API credentials
   • 100+ languages
   • Good general coverage

3. AWS Translate

   • Configure AWS credentials
   • Enterprise features
   • Custom terminology

Using Auto-Translate

1. Select text to translate
2. Click “Auto-translate”
3. Choose translation provider
4. Review and edit suggestion
5. Save translation

Collaborative Features

Team Roles

• Translators - Create and edit translations
• Reviewers - Review translation quality
• Approvers - Final approval for publication
• Managers - Manage team and settings

Translation Workflow

1. Creation - Translator adds translation
2. Review - Reviewer checks quality
3. Revision - Address feedback if needed
4. Approval - Approver publishes
5. Live - Translation goes live

Custom Attributes

Translate custom fields in your models:

{
  resolve: "@hicity/medusa-plugin-tolgee",
  options: {
    custom_attributes: {
      product: [
        "seo_title",
        "seo_description",
        "features",
        "specifications",
      ],
      product_variant: [
        "size_guide",
        "material_description",
      ],
      collection: [
        "hero_title",
        "hero_description",
      ],
      category: [
        "meta_keywords",
      ],
    },
  },
}

Language Management

Adding Languages

In Tolgee dashboard:

1. Navigate to Languages section
2. Add new language (ISO code)
3. Set language properties
4. Sync with Medusa

Supported Languages

Any language with ISO 639-1 code:

• English (en)
• Spanish (es)
• French (fr)
• German (de)
• Japanese (ja)
• Chinese (zh)
• Arabic (ar)
• And 100+ more

Translation States

Track progress with translation states:

• Untranslated - No translation exists yet
• Translated - Initial translation added
• Reviewed - Reviewed by team member
• Approved - Approved and ready for use
• Outdated - Source text changed

Best Practices

1. Quality Over Speed - Review AI translations
2. Consistency - Use translation memory
3. Context - Provide context for translators
4. Regular Updates - Keep translations current
5. Test Thoroughly - Test in all languages
6. Backup - Export translations regularly
7. Team Training - Train team on Tolgee

Use Cases

International E-commerce

• Multi-country product catalogs
• Localized marketing content
• Regional SEO optimization

Multi-Brand Stores

• Brand-specific translations
• Market-specific messaging
• Local compliance

Global Marketplaces

• Seller multilingual support
• Customer multi-language
• International shipping info

Performance Optimization

Caching Strategy

The plugin implements caching:

• Translations cached on load
• Background sync for updates
• Minimal performance impact

Best Practices

• Batch sync during low traffic
• Use CDN for static translations
• Implement lazy loading
• Cache frequently accessed content

Links

• Tolgee Platform
• Tolgee Documentation
• Tolgee React SDK