手动覆盖

使用 data-lingo-override 属性为特定文本覆盖 AI 生成的翻译。

基本用法

<h1 data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
  Lingo.dev
</h1>

编译器会使用你指定的翻译，而不是通过 AI 生成翻译。

语法

data-lingo-override 属性接受一个以语言环境代码为键的对象：

data-lingo-override={{
  [locale]: "translation",
  ...
}}

语言环境代码 必须与你配置的 targetLocales 保持一致。该属性会在最终 HTML 输出中被移除。

使用场景

品牌名称

在所有语言环境中保持品牌名称一致：

<h1 data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev", fr: "Lingo.dev" }}>
  Lingo.dev
</h1>

技术术语

确保技术术语一致：

<p data-lingo-override={{ es: "API REST", de: "REST-API", ja: "REST API" }}>
  REST API
</p>

法律文本

为法律内容使用认证翻译：

<p data-lingo-override={{
  es: "Todos los derechos reservados. Consulte nuestros términos legales.",
  de: "Alle Rechte vorbehalten. Siehe unsere rechtlichen Bedingungen."
}}>
  All rights reserved. See our legal terms.
</p>

市场营销文案

优化营销信息：

<h2 data-lingo-override={{
  es: "Traduce tu app en minutos",
  de: "Übersetze deine App in Minuten",
  fr: "Traduisez votre app en quelques minutes"
}}>
  Translate your app in minutes
</h2>

部分覆盖

只覆盖特定语言环境，其他语言环境使用 AI 翻译：

<p data-lingo-override={{ de: "Professionelle Übersetzung" }}>
  Professional translation
</p>

西班牙语、法语及其他语言区域使用 AI 翻译。只有德语使用了你的自定义覆盖。

富文本与插值

编译器支持带有嵌套元素的富文本：

<p data-lingo-override={{
  es: "Bienvenido <strong0>{name}</strong0>",
  de: "Willkommen <strong0>{name}</strong0>"
}}>
  Welcome <strong>{name}</strong>
</p>

占位符语法：

  • <tagname0>...</tagname0> 表示标签的第一次出现
  • <tagname1>...</tagname1> 表示第二次出现
  • {variableName} 表示插值

编译器会自动将 <strong0> 映射回输出中的 <strong>。

多重嵌套元素

<div data-lingo-override={{
  es: "Tu pedido: <span0>{count}</span0> artículos por <em0>${price}</em0>",
  de: "Deine Bestellung: <span0>{count}</span0> Artikel für <em0>${price}</em0>"
}}>
  Your order: <span>{count}</span> items for <em>${price}</em>
</div>

复杂示例

嵌套组件

<section>
  <h1 data-lingo-override={{ es: "Características", de: "Funktionen" }}>
    Features
  </h1>
  <p data-lingo-override={{
    es: "Traduce automáticamente tus componentes React sin cambios de código",
    de: "Übersetze deine React-Komponenten automatisch ohne Code-Änderungen"
  }}>
    Automatically translate your React components without code changes
  </p>
</section>

属性

同样支持字符串属性：

<img
  src="/logo.png"
  alt="Company Logo"
  data-lingo-override={{
    es: "Logo de la Empresa",
    de: "Firmenlogo"
  }}
/>

该覆盖应用于 alt 属性。

区域语言代码

支持区域语言代码（例如 en-US、en-GB）：

<p data-lingo-override={{
  "en-US": "color",
  "en-GB": "colour",
  "es-ES": "color",
  "es-MX": "color"
}}>
  color
</p>

带连字符的区域代码请使用引号。

TypeScript 支持

使用 TypeScript 时，该属性具有完整类型支持：

interface OverrideProps {
  "data-lingo-override"?: Record<string, string>;
}

TypeScript 会校验区域代码是否与你配置的 targetLocales 匹配。

最佳实践

请谨慎使用——大部分翻译交给 AI 处理，仅在必要时覆盖：

  • 不应翻译的品牌名称
  • 需要特定翻译的技术术语
  • 需要认证的法律文本
  • 需要人工审核的市场营销文案

保持一致性 — 在应用中对相同术语使用 override：

// Good - consistent brand name
<h1 data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>Lingo.dev</h1>
<p>Welcome to <span data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>Lingo.dev</span></p>

// Bad - inconsistent
<h1 data-lingo-override={{ es: "Lingo.dev" }}>Lingo.dev</h1>
<p>Welcome to Lingo.dev</p> // Missing override

版本控制 — override 字符串位于源代码中，便于审查和版本管理。

常见问题

这适用于 Client Components 吗？ 可以。override 适用于 Server 和 Client Components。

可以 override 属性如 aria-label 吗？ 可以。无论是元素内容还是属性，只要是可翻译文本都可以 override。

如果我只 override 某一个语言环境会怎样？ 其他语言环境会使用 AI 翻译。override 是按语言环境区分的，无需为所有语言环境指定。

override 可以用变量吗？ 可以。使用 {variableName} 语法进行插值。编译器会保留变量占位符。

override 会增加 bundle 体积吗？ 会略微增加。每个 override 会为 bundle 增加几个字节。合理使用时影响可以忽略不计。

可以只在开发环境中 override 吗？ 不可以。override 属于源代码，适用于所有环境。如需临时测试，请使用开发小部件。

后续步骤