Replexica Docs

Appearance

DatoCMS Integration ​

Replexica seamlessly integrates with DatoCMS. This integration enables automated localization of your content directly through the DatoCMS API. Unlike local file formats, it works with remotely stored data. This makes it perfect for reusing existing Replexica localization engine memory across multiple projects.

Prerequisites ​

Before setting up Replexica integration, you need to enable localization in your DatoCMS project:

  1. Go to your DatoCMS account, select your project, then navigate to "Configuration" > "Locales and Timezones" (or visit the configuration/locales-and-timezone URL directly);
  2. Select the languages you want to support;
  3. Set your primary language - it should go first in the list (this should match the source in your i18n.json).

Understanding DatoCMS Concepts ​

Before setting up, let's understand the key DatoCMS concepts:

  1. Project: Your DatoCMS workspace where all your content lives. Each project has a unique ID that you can find in your project's URL or Settings > Project Settings.

  2. Model: A content type definition in DatoCMS (like "Blog Post", "Product", or "Documentation Page"). Models define the structure of your content. Find model IDs in Settings > Models > [Your Model] > Settings tab.

  3. Record: An individual piece of content created from a model (like a specific blog post or product). Each record has a unique ID visible in its URL when editing.

  4. Field: A specific content attribute in a model (like "title", "description", or "content"). Field IDs are the API identifiers visible in the model builder interface.

Setting Up ​

Create a configuration file in your project. Here's an example with explanations:

json5
{
  // Project ID from Settings > Project Settings
  "project": "146425",
  
  // Model ID from Settings > Models > [Your Model] > Settings
  "model": "documentation_page",
  
  // Optional: Specific record IDs to translate
  // Find these in the URL when editing a record
  "records": [
    "185834003"
  ],
  
  // Field IDs from your model's configuration
  // These are the API identifiers visible in the model builder
  "fields": [
    "title",
    "subtitle",
    "content"
  ]
}

Configuration in i18n.json ​

Add the DatoCMS configuration to your i18n.json:

json
{
  "version": 1.2,
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "dato": {
      "include": [
        "demo/dato/documentation_page.json5",
        "demo/dato/change_log.json5"
      ]
    }
  }
}

Authentication ​

Get your DatoCMS API token:

  1. Go to Settings > API tokens in your DatoCMS project

  2. Create a new full-access API token

  3. Set it up in one of two ways:

    Option 1: Environment Variable

    bash
    export DATO_API_TOKEN=your_api_token_here

    Option 2: .env File Create a .env file in your project root:

    env
    DATO_API_TOKEN=your_api_token_here

Running Translations ​

With your configuration set, run:

bash
npx replexica@latest i18n

Replexica will:

  1. Connect to your DatoCMS project
  2. Enable localization for specified fields if not already enabled
  3. Fetch content from the source language
  4. Translate to target languages
  5. Push translations back to DatoCMS

Supported Content Types ​

The integration supports two types of content:

  1. String Fields: Simple text fields like titles, descriptions, or metadata
  2. Structured Text (DAST): DatoCMS's rich text format, including:
    • Paragraphs
    • Headers
    • Lists
    • Rich text formatting
    • Links
    • Embedded content

Pro Tips ​

  1. Selective Translation: Use the records field to translate specific content:

    json5
    {
  "project": "146425",
  "model": "documentation_page",
  // We support JSON5 format, so you can add descriptive comments
  // for better maintainability and documentation
  "records": [
    "185834003",  // Homepage content
    "185834004",  // About us page
    "185834005"   // Product documentation
  ],
  "fields": ["title", "content"]
}

  2. Field Selection: Only specify fields that need translation:

    json5
    {
  "fields": [
    "title",       // Translate this
    "content",     // And this
    // "created_at" // But not this
  ]
}

  3. Quality Control: Use interactive mode for reviewing translations of critical content

  4. Frozen Mode: Use --frozen to ensure content hasn't changed:

    bash
    npx replexica@latest i18n --frozen

Error Handling ​

The integration includes robust error handling:

  • Invalid API keys
  • Missing permissions
  • Network issues
  • Invalid field configurations

Each error includes detailed information to help you resolve the issue quickly.

Best Practices ​

  1. Version Control: Keep your DatoCMS configuration files in version control
  2. API Token Security: Never commit your DATO_API_TOKEN - use environment variables
  3. Regular Updates: Run translations regularly to keep content in sync
  4. Testing: Test translations on staging before applying to production content
  5. Field Setup: Ensure fields are properly configured for localization in DatoCMS
  6. Content Modeling: Design your content models with translation in mind

By leveraging these features, you can maintain a robust, automated localization workflow for your DatoCMS content. The integration handles the complexity of API interactions, allowing you to focus on content creation while ensuring your content reaches a global audience.