Lingo.dev Docs

Appearance

DatoCMS Integration ​

Lingo.dev 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 Lingo.dev localization engine memory across multiple projects.

Prerequisites ​

Before setting up Lingo.dev 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 (required)
  project: "146425",

  // Optional: Configure models to translate
  models: {
    // Model ID as the key
    documentation_page: {
      // Optional: Specific record IDs to translate
      records: ["185834003"],
      // Optional: Field IDs to translate
      fields: ["title", "subtitle", "content"],
    },
    blog_post: {
      fields: ["title", "content"],
    },
  },
}

Only the project field and DATO_API_TOKEN environment variable are required. The models configuration will be automatically updated when you use the CLI's interactive mode to select content for translation.

The configuration structure means:

  • project: Your DatoCMS project ID
  • models: A map of model IDs to their translation settings
    • Each model can specify optional records (specific content to translate)
    • Each model can specify optional fields (which fields to translate)

Important

Both your DatoCMS configuration file and the generated i18n.lock lockfile must be committed to version control. The lockfile tracks translation states and ensures consistency across your team.

While the DATO_API_TOKEN should be kept secure in environment variables, all other configuration files should be tracked in git.

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/config.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 lingo.dev@latest i18n

Lingo.dev 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",
  models: {
    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
    {
  project: "146425",
  models: {
    documentation_page: {
      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 lingo.dev@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.

Known Limitations

When working with rich text content in DatoCMS (e.g. article content, blog posts, etc.), the structure of the target language content must match the source content structure before running the Lingo.dev translation command. This means:

  • Target language content should not be empty
  • Target language content should maintain the same paragraphs, images, and styling as the source
  • Removing or modifying structural elements in target languages will cause issues

By default, DatoCMS automatically copies the source language content to target languages when localization is enabled, so this shouldn't be a significant concern.

However, if you find this workflow suboptimal for your use case, please reach out to [email protected], and we will suggest alternative approaches. 👌