PHP小码农

Appearance

translate 翻译控制 ​

translate 全局属性用于告知浏览器和翻译工具（如 Google Translate）某个元素的内容是否应该被翻译。这个属性在多语言网站、专业术语、品牌名称等场景下非常有用，可以防止翻译引擎错误地翻译不应翻译的内容。

前置知识

阅读本节前，建议先了解：hidden 隐藏

基础概念 ​

什么是 translate 属性 ​

translate 是一个枚举型全局属性，值为 yes 或 no，用于控制元素内容是否应该被翻译：

  • translate="yes" -- 内容可以被翻译（默认值）
  • translate="no" -- 内容不应被翻译
html
<!-- 默认行为：内容可被翻译 -->
<p>欢迎使用我们的产品</p>

<!-- 禁止翻译：品牌名称 -->
<p>本产品由 <span translate="no">Vue.js</span> 驱动</p>

<!-- 禁止翻译：代码标识符 -->
<p>请在终端中输入 <code translate="no">npm install</code></p>

何时使用 translate="no" ​

场景示例原因
品牌名称<span translate="no">Google</span>保持品牌一致性
产品名称<span translate="no">iPhone 15</span>避免翻译为奇怪的结果
代码片段<code translate="no">console.log()</code>代码不应被翻译
API 端点<code translate="no">/api/v1/users</code>URL 路径不应翻译
人名<span translate="no">张三</span>人名通常不翻译
地址<span translate="no">北京市朝阳区</span>地址保持原样
用户名<span translate="no">@zhangsan</span>用户名不翻译
技术术语<span translate="no">WebSocket</span>技术术语需保持原文

语法 ​

html
<!-- 允许翻译（默认） -->
<p translate="yes">这段文字会被翻译</p>
<p>这段文字也会被翻译（默认行为）</p>

<!-- 禁止翻译 -->
<p translate="no">这段文字不会被翻译</p>

<!-- 布尔属性写法 -->
<p translate>这段文字会被翻译</p>

JavaScript 操作 ​

javascript
const el = document.querySelector('.brand');

// 设置不可翻译
el.translate = false;      // 等效于 translate="no"
el.setAttribute('translate', 'no');

// 设置可翻译
el.translate = true;       // 等效于 translate="yes"
el.setAttribute('translate', 'yes');

// 读取当前值
console.log(el.translate);  // true 或 false
console.log(el.getAttribute('translate'));  // "yes" 或 "no"

详细说明 ​

继承行为 ​

translate 属性遵循 DOM 继承规则，子元素会继承父元素的 translate 设置：

html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>translate 继承示例</title>
</head>
<body>
  <!-- 整个代码块禁止翻译 -->
  <pre translate="no">
    // 代码块中的所有内容都不会被翻译
    const name = "Hello World";
    console.log(name);
  </pre>

  <!-- 段落中部分内容禁止翻译 -->
  <p>
    请访问我们的
    <a href="https://example.com" translate="no">GitHub Repository</a>
    查看源代码。
  </p>

  <!-- 品牌信息块 -->
  <div translate="no">
    <h2>Acme Corporation</h2>
    <p>CEO: John Smith</p>
    <p>Founded: 2020</p>
  </div>

  <!-- 子元素可以覆盖父元素的设置 -->
  <div translate="no">
    <h2>品牌信息</h2>
    <!-- 覆盖父级：这段可以翻译 -->
    <p translate="yes">点击这里了解更多关于我们的产品。</p>
  </div>
</body>
</html>

与 lang 属性配合 ​

当页面中混合多种语言时，translate 和 lang 属性应配合使用：

html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>多语言页面中的 translate</title>
</head>
<body>
  <h1>技术博客</h1>

  <!-- 英文引用，标注 lang，不翻译 -->
  <blockquote lang="en" translate="no">
    "Any fool can write code that a computer can understand.
    Good programmers write code that humans can understand."
    <cite>-- Martin Fowler</cite>
  </blockquote>

  <!-- 混合语言内容 -->
  <p>
    本教程使用
    <span lang="en" translate="no">React</span> 框架，配合
    <span lang="en" translate="no">TypeScript</span> 进行开发。
  </p>

  <!-- 技术文档中的命令行示例 -->
  <div lang="en" translate="no">
    <code>$ git clone https://github.com/user/repo.git</code>
    <code>$ cd repo && npm install</code>
    <code>$ npm run dev</code>
  </div>
</body>
</html>

翻译工具的支持情况 ​

翻译工具translate 属性支持说明
Google Translate支持尊重 translate="no" 设置
Microsoft Translator部分支持可能不完全遵守
DeepL有限支持主要通过 class="notranslate" 识别
Bing 翻译支持尊重 translate="no"

注意

某些翻译工具可能不完全遵守 translate 属性。为了最大兼容性，可以同时使用 class="notranslate" 作为备选方案。

html
<!-- 最大兼容性写法 -->
<span translate="no" class="notranslate">Vue.js</span>

实战示例 ​

多语言技术文档 ​

html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>多语言技术文档</title>
  <style>
    .cmd-block {
      background: #1e293b;
      color: #e2e8f0;
      padding: 16px;
      border-radius: 8px;
      font-family: monospace;
      overflow-x: auto;
    }

    .term {
      color: #f59e0b;
      font-weight: 600;
    }
  </style>
</head>
<body>
  <article>
    <h1>使用 Docker 部署应用</h1>

    <p>
      本指南将教你如何使用
      <span class="term" translate="no">Docker</span> 和
      <span class="term" translate="no">Docker Compose</span>
      部署一个基于
      <span class="term" translate="no">Node.js</span> 的
      <span class="term" translate="no">REST API</span> 应用。
    </p>

    <!-- 代码块整体不翻译 -->
    <div class="cmd-block" translate="no">
      <p>$ docker pull node:18-alpine</p>
      <p>$ docker build -t my-app .</p>
      <p>$ docker run -p 3000:3000 my-app</p>
    </div>

    <h2>docker-compose.yml 配置</h2>

    <!-- 配置文件内容不翻译 -->
    <pre translate="no"><code>version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DB_HOST=db
  db:
    image: postgres:15
    environment:
      - POSTGRES_DB=myapp
      - POSTGRES_PASSWORD=secret</code></pre>

    <p>
      上面的配置定义了两个服务：<code translate="no">app</code> 和
      <code translate="no">db</code>。
      <code translate="no">app</code> 服务运行我们的
      <span class="term" translate="no">Node.js</span> 应用，
      <code translate="no">db</code> 服务运行
      <span class="term" translate="no">PostgreSQL</span> 数据库。
    </p>
  </article>
</body>
</html>

用户生成内容页面 ​

html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>用户资料页</title>
</head>
<body>
  <div class="user-profile">
    <h2>用户信息</h2>

    <!-- 用户名不翻译 -->
    <p>用户名：<span translate="no">@web_developer_2024</span></p>

    <!-- 真实姓名不翻译 -->
    <p>姓名：<span translate="no">王小明</span></p>

    <!-- 城市/地址不翻译 -->
    <p>所在城市：<span translate="no">上海市浦东新区</span></p>

    <!-- 个人简介可翻译 -->
    <p class="bio">一名热爱前端开发的程序员，擅长使用 Vue.js 和 React。</p>

    <!-- 技能标签不翻译 -->
    <div class="skills">
      <span translate="no" class="tag">JavaScript</span>
      <span translate="no" class="tag">TypeScript</span>
      <span translate="no" class="tag">Vue.js</span>
      <span translate="no" class="tag">React</span>
      <span translate="no" class="tag">Node.js</span>
    </div>
  </div>
</body>
</html>

注意事项 ​

不要过度使用 translate="no" ​

html
<!-- 错误：不应翻译正常文本 -->
<p translate="no">欢迎来到我们的网站</p>

<!-- 正确：只标记不应翻译的内容 -->
<p>欢迎来到 <span translate="no">Acme Corp</span> 的官方网站</p>

class="notranslate" 的历史 ​

在 translate 属性被广泛支持之前，Google Translate 使用 class="notranslate" 来标记不应翻译的元素：

html
<!-- 传统方式（仍然有效） -->
<span class="notranslate">Brand Name</span>

<!-- 现代方式 -->
<span translate="no">Brand Name</span>

<!-- 两者结合，最大兼容 -->
<span translate="no" class="notranslate">Brand Name</span>

translate 不影响屏幕阅读器 ​

translate 属性不影响屏幕阅读器的语音输出。如果需要控制语音输出语言，应使用 lang 属性：

html
<!-- translate="no" 防止翻译工具翻译 -->
<!-- lang="en" 指导屏幕阅读器使用英语发音 -->
<span lang="en" translate="no">JavaScript</span>

最佳实践 ​

1. 为代码和技术内容使用 translate ​

html
<!-- 推荐模式 -->
<article>
  <h1>JavaScript 异步编程指南</h1>
  <p>
    本教程介绍 <span translate="no">JavaScript</span> 中的
    <span translate="no">Promise</span>、
    <span translate="no">async/await</span> 等
    <span translate="no">ES6+</span> 异步特性。
  </p>

  <!-- 整块代码禁止翻译 -->
  <pre translate="no"><code>async function fetchData() {
  const response = await fetch('/api/data');
  const data = await response.json();
  return data;
}</code></pre>
</article>

2. 与 i18n 系统配合 ​

javascript
// 在国际化系统中，标记不翻译的元素
const i18n = {
  brandName: 'Acme Corp',  // 品牌名不翻译
  greeting: '欢迎回来',    // 可翻译内容
};

document.querySelector('.brand').textContent = i18n.brandName;
document.querySelector('.brand').setAttribute('translate', 'no');

3. 数据驱动的 translate 标记 ​

javascript
// 自动为技术术语添加 translate="no"
const techTerms = ['JavaScript', 'TypeScript', 'React', 'Vue.js', 'Node.js',
  'Docker', 'Kubernetes', 'PostgreSQL', 'Redis', 'API', 'REST', 'GraphQL'];

function markTechTerms(element) {
  techTerms.forEach(term => {
    // 使用 TreeWalker 遍历文本节点
    const walker = document.createTreeWalker(
      element,
      NodeFilter.SHOW_TEXT,
      null
    );

    while (walker.nextNode()) {
      const node = walker.currentNode;
      const regex = new RegExp(`\\b${term}\\b`, 'g');
      if (regex.test(node.textContent)) {
        const span = document.createElement('span');
        span.setAttribute('translate', 'no');
        span.textContent = term;
        node.parentNode.replaceChild(span, node);
      }
    }
  });
}

下一节

继续学习：part 与 exportparts

参考链接 ​