CFW网站多语言切换实操：30分钟极速搞定全球本地化

各位出海的朋友们，大家好！在咱们跨境业务中，网站本地化一直是个绕不开的话题。想让全球用户都能无障碍地访问你的网站，看得懂你的产品介绍，多语言支持是标配。但怎么才能做到既高效又省心，还不用给服务器加太多负担呢？今天，咱们新媒网跨境就给大家揭秘一个实战利器——Cloudflare Workers，搭配SimpleLocalize，让你轻松搞定网站的多语言切换，实现真正的“一站式”服务。

一、为什么选择Cloudflare Workers来做本地化？

想象一下，你的网站就像一个对外开放的店铺。如果客人来自不同国家，你总不能每来一个客人，就临时找个翻译吧？最理想的状态是，店铺里有个智能“翻译机”，能根据客人的语言自动切换。Cloudflare Workers扮演的正是这个角色。

它就像部署在全球各地的“小助手”，用户一访问你的网站，它就能在内容到达用户浏览器之前，先把网站内容“翻译”成本地语言。整个过程不需要你在服务器上安装任何额外插件，不增加服务器压力，响应速度还快得惊人。咱们这次就用一个托管在GitHub Pages上的静态HTML网站来演示，但请放心，这套方法对那些用React、Angular、Vue.js等主流框架搭建的动态网站也同样适用。

二、动手之前，咱们得先准备好几样东西：

Cloudflare账号： 这是核心，没有它，Workers就没法部署。
SimpleLocalize账号： 用来集中管理咱们网站的翻译内容，非常方便。
JavaScript和Web开发基础： 别担心，不需要是高级程序员，有点基础就行，因为我会一步步带着大家来。

三、这套本地化方案，究竟是怎么运作的？
proxy

简单来说，Cloudflare Worker就像一个智能“代理”，它会站在用户和你的源网站之间。当用户发起请求时，Worker会先“拦截”下来。接着，它会检查用户请求里有没有带lang（语言）参数。如果带了，比如?lang=es，那它就知道用户想看西班牙语内容。如果没有，Worker就会使用咱们默认设定的语言。在后续的教程中，咱们还会学到怎么利用用户浏览器发送的Accept-Language头信息来自动判断用户的首选语言。

而网站上的具体翻译内容，咱们会把它托管在SimpleLocalize的翻译CDN上。这样一来，全球各地的用户都能快速、高效地获取到最新的本地化内容。

四、实战演练：以一个简单网站为例

为了让大家看得更明白，咱们先拿一个简单的HTML网站举例。这个网站有几段文字需要做本地化，同时还有三个按钮，用来让用户手动切换语言。
Static HTML website hosted on GitHub Pages

我在需要翻译的HTML元素上，添加了一个data-i18n-key的属性。比如：

<!-- 原来是这样 -->
<h3 class="mt-3">Hello World</h3>
<!-- 加上key之后是这样 -->
<h3 class="mt-3" data-i18n-key="hello_world">Hello World</h3>

同时，语言切换按钮也做了类似的处理：

<a href="?lang=en" data-i18n-key="languages.english">English</a>
<a href="?lang=pl" data-i18n-key="languages.polish">Polish</a>
<a href="?lang=es" data-i18n-key="languages.spanish">Spanish</a>

至于这些key的名字怎么定，完全取决于你。新媒网跨境认为，采用层级结构是个好习惯，这样能让你的翻译键保持整洁有序，方便管理。

五、在SimpleLocalize上设置你的翻译内容

现在，咱们把网站的“骨架”搭好了，接下来就是给它“填肉”——翻译内容。我已经在SimpleLocalize上创建了一个项目，里面包含了上面示例网站的所有翻译键，并且自动翻译成了西班牙语和波兰语。
SimpleLocalize project with translation keys

我还把这些翻译内容发布到了SimpleLocalize的CDN上。这样，这些翻译内容就可以通过以下链接快速访问了（记得把{your-project-token}换成你自己的项目Token）：

英文：https://cdn.simplelocalize.io/{your-project-token}/_latest/en
西班牙语：https://cdn.simplelocalize.io/{your-project-token}/_latest/es
波兰语：https://cdn.simplelocalize.io/{your-project-token}/_latest/pl

六、重头戏来了：搭建Cloudflare Workers！

接下来，咱们就要在Cloudflare上把这个“翻译官”搭建起来了。

第一步：创建Worker应用。

登录你的Cloudflare后台，找到“Workers & Pages”这个版块，点击“创建应用程序”按钮，然后选择“创建Worker”就好。
Create Cloudflare Worker

第二步：粘贴核心代码。

创建好Worker之后，你会在编辑器里看到一些默认代码。咱们把下面的核心代码粘贴进去，并替换掉PROJECT_TOKEN、DEFAULT_LANGUAGE和BASE_URL这些占位符，换成你自己的项目Token、默认语言和网站URL。

这段代码中的addEventListener('fetch', event => { event.respondWith(handleEvent(event)); });是Workers的入口，它会监听所有发往Worker的请求。

const DEBUG = true; // 设置为true可以绕过缓存，方便调试
const DEFAULT_LANGUAGE = "en"; // 替换成你的默认语言
const PROJECT_TOKEN = "YOUR-PROJECT-TOKEN"; // 替换成你的项目Token
const ENVIRONMENT = "_latest"; // 替换成你的环境名称，一般默认_latest
const BASE_URL = "https://example.com"; // 替换成你的网站URL，也就是源站地址

addEventListener('fetch', event => {
  event.respondWith(handleEvent(event));
});

第三步：添加两个处理类。

咱们再给Worker代码加上ElementHandler和LangHandler这两个类。

class ElementHandler {
  constructor(countryStrings) {
    this.languageTranslations = countryStrings; // 存储当前语言的翻译内容
  }

  element(element) {
    const i18nKey = element.getAttribute('data-i18n-key'); // 获取HTML元素上的翻译键
    if (i18nKey) {
      const translation = this.languageTranslations[i18nKey]; // 根据键查找对应的翻译
      if (translation) {
        element.setInnerContent(translation); // 如果找到，就替换元素内容
      }
    }
  }
}

class LangHandler {
  constructor(language) {
    this.language = language; // 存储当前语言
  }

  element(element) {
    element.setAttribute('lang', this.language); // 设置HTML元素的lang属性
  }
}

ElementHandler这个类呢，它的任务就是把HTML元素中所有带有data-i18n-key属性的内容，替换成对应语言的翻译。举个例子：

<!-- 替换之前 -->
<h3 class="mt-3" data-i18n-key="hello_world">Hello World</h3>
<!-- 替换之后，如果是西班牙语 -->
<h3 class="mt-3" data-i18n-key="hello_world">Hola Mundo</h3>

LangHandler就简单多了，它负责把整个HTML文档的lang属性，设置为当前语言。比如：
```

<html lang="en">

<html lang="es">
```

第四步：添加获取翻译的函数。

接着，咱们需要一个getTranslations函数，它能根据咱们指定的语言键，从SimpleLocalize的CDN上把翻译内容拉取下来。

async function getTranslations(languageKey) {
  // 向SimpleLocalize的CDN发起请求，获取指定语言的JSON翻译文件
  return await fetch(`https://cdn.simplelocalize.io/${PROJECT_TOKEN}/${ENVIRONMENT}/${languageKey}`)
    .then(response => response.json()) // 成功后解析为JSON格式
    .catch(() => ({})); // 如果失败，返回一个空对象，避免程序报错
}

第五步：完善请求处理函数handleEvent。

最后，也是最核心的部分，就是handleEvent函数。所有的请求都会在这里被处理，它会根据用户的语言偏好，返回相应的本地化内容。

async function handleEvent(event) {
  const url = new URL(event.request.url); // 解析请求的URL
  const pathname = url.pathname; // 获取请求路径
  const fetchOptions = {
    cacheControl: {
      bypassCache: DEBUG // 调试模式下，不使用缓存
    }
  };

  try {
    // 优先从URL参数中获取语言，如果没有，就使用默认语言
    const languageKey = url.searchParams.get('lang') ?? DEFAULT_LANGUAGE;
    // 获取对应语言的翻译内容
    const translations = await getTranslations(languageKey);
    // 从源站获取原始HTML内容
    const originalContentAtPath = await fetch(BASE_URL + pathname, fetchOptions);

    // 使用HTMLRewriter来转换HTML内容
    return new HTMLRewriter()
      .on('[data-i18n-key]', new ElementHandler(translations)) // 用ElementHandler替换翻译键对应的内容
      .on('[lang]', new LangHandler(languageKey)) // 用LangHandler设置lang属性
      .transform(originalContentAtPath); // 对原始内容进行转换
  } catch (e) {
    console.error(e);
    // 出现错误时，返回404 Not found
    return new Response(`Not found`, { status: 404 });
  }
}

新媒网跨境了解到，不少朋友在面对代码时会有点犯怵，但这段代码其实思路很清晰：它先判断用户想看什么语言，然后去SimpleLocalize把对应语言的翻译“字典”拿过来，接着抓取你的源网站内容，最后用HTMLRewriter这个工具，把源网站内容里所有需要翻译的地方，都根据“字典”给换掉，完美！

这段完整的代码，大家可以在Cloudflare Workers and Website Localization这个仓库里找到。

第六步：保存并部署Worker。

代码都贴好了之后，点击“保存并部署”按钮。这样，你的Worker就会部署到Cloudflare的网络上，开始为你工作了。
i18n Cloudflare Worker

重要提醒： 部署完成后，你必须通过Cloudflare分配给你的Worker域名来访问网站，才能看到效果。如果你直接访问原来的网站域名，Worker是不会被触发的。当然，你也可以在Cloudflare后台的“路由”部分，配置Worker路由来匹配你的网站域名和路径，这样用户访问你的主域名也能触发Worker。这部分咱们会在后续教程中详细讲解。

七、测试你的Cloudflare Worker

要测试你的Worker是否工作正常，只需要在你的网站URL后面加上lang查询参数，指定你想要的语言。比如，在URL末尾加上?lang=es，就能看到西班牙语的网站内容了。

亲自试一试，你会发现切换语言是多么流畅！

八、小结与展望

看到这里，相信大家对如何利用Cloudflare Workers搭建网站本地化功能，已经有了一个清晰的认识。我们通过lang查询参数来指定语言，实现了网站内容的动态切换，并且把SimpleLocalize作为了所有翻译内容的“单一事实来源”。这种方式既减轻了服务器负担，又提升了用户体验，完美！

当然，技术的世界瞬息万变，咱们跨境人更要紧跟潮流。本次教程只是个开始，在后续的系列教程中，新媒网跨境还会带大家深入探讨：