在玩Tolgee的过程中，我将知名的开源公司dub.co翻译成了多种语言！这花了我一个小时，结果真是令人惊讶！

……（此处可能表示分隔或引文开始）

在本教程中，我将引导你了解一种简单而高效的使用Tolgee进行本地化的方法。

你还将学习如何将Tolgee集成到Dub.co中，它是一个流行的应用链接管理平台，允许用户以他们偏好的语言来访问和使用该应用程序。

先决条件

要彻底理解本教程，你需要对 React 或 Next.js 有一些基本知识。

你还需要配置以下内容：

• Tolgee 项目 - 一个已有的项目，它至少包含了两种语言的翻译。
• Tolgee CLI - 允许你通过命令行与 Tolgee 平台进行通信。
• Docker - 运行 Dub.co 所必需的。它是一个开源平台，使用容器化技术使创建、部署和运行应用程序变得简单。
• Docker Compose - 定义和运行多容器 Docker 应用程序的工具。
• Python (版本 3.8 或更高)：配置 Dub.co 某些包时需要的。

……

或者使用中文中的省略号 "......" 来表示省略的内容。

你知道Tolgee是什么吗？

Tolgee 是一个面向开发者的友好本地化平台，允许你轻松地将应用程序翻译成任何语言，而无需修改代码。它专为 web 应用程序设计，同时也支持移动和桌面应用程序。

使用 Tolgee，你无需在源代码中查找键值，编辑本地化文件，或手动导出数据给翻译人员。Tolgee 提供上下文翻译、翻译记忆库来追踪已翻译的字符串、机器翻译和自动翻译等功能，以及其他更多功能。

](https://imgapi.imooc.com/672c5c59091ac21708000457.jpg)

请给我们点个赞哦，谢谢啦！

这能帮我们写更多这样的文章 💖

给 Tolgee 仓库点个赞⭐

……

如何在本地电脑上设置 Dub.co：

Dub.co 是一个开源链接管理平台，让营销团队能够为他们的链接添加强大的分析功能，创建短链接，生成链接二维码等功能。它是由前 Vercel 员工 Steven Tey 创建的。

按照以下步骤，在您的电脑上安装Dub.co：

复制Dub.co GitHub仓库，并运行下面的代码。

运行以下命令来克隆仓库：

git clone https://github.com/dubinc/dub.git

点击全屏 点击退出

导航到 dub 文件夹，然后安装项目所需的依赖项：

pnpm install
# 在项目中安装依赖包

全屏显示，退出全屏

在 apps/web 文件夹中，将 .env.example 文件改名为 .env。

创建一个新的Tinybird账户，然后将 管理员认证令牌 复制到项目根目录下的 .env 文件中。

TINYBIRD_API_KEY=你的管理员API令牌

全屏；退出全屏

进入 packages/tinybird 目录，并使用以下命令安装 Tinybird CLI，注：CLI 为命令行界面的缩写。

命令如下：
pip3 install tinybird-cli

全屏 退出全屏

在命令行终端中运行以下命令，并在使用Tinybird命令行工具身份验证时输入您的管理员认证令牌：

[tb认证](tb zhènhèn)

全屏模式 退出全屏

发布 Tinybird 的数据源和端点，运行如下代码：

推送tb（可能是指某个特定的操作或命令，具体含义需要根据上下文确定）

点击全屏按钮 点击退出全屏按钮

创建一个Upstash数据库，在REST API部分找到以下凭据，并复制到你的.env文件中。

UPSTASH_REDIS_REST_URL=<请填入你的REST_URL>
UPSTASH_REDIS_REST_TOKEN=<请填入你的REST_TOKEN>

全屏模式 退出全屏

点击进入 QStash 标签页 并将以下凭证复制进 .env 文件中。

    QSTASH_TOKEN=
    QSTASH_CURRENT_SIGNING_KEY=
    QSTASH_NEXT_SIGNING_KEY=

    //这些是QStash系统中的变量名称

全屏模式（进入/退出）

接下来，在 apps/web 目录中，执行以下命令来启动 Docker Compose stack：
（在“堆栈”一词前保留英文原词以确保准确性）

docker-compose up

进入全屏 退出全屏

生成 Prisma 客户端并创建其数据库表，可以使用以下命令：

（具体命令请参考相应文档或示例）

运行生成命令：`npx prisma generate` 和 推送数据库命令：`npx prisma db push`

全屏 退出全屏

Dub.co 支持多种身份验证方法。创建一个 GitHub 应用，然后将以下 URL 复制为其回调 URL。

http://localhost:8888/api/auth/callback/github （这是用于GitHub回调的身份验证API）

全屏 退出全屏

最后，运行开发服务器吧：

    pnpm dev

全屏模式，退出全屏

你可以通过访问 http://localhost:8888 来访问该网络应用程序，创建一个新的工作区并开始使用吧。如果遇到任何问题的话，请查阅详细的安装指南以获取更多帮助。

---

在 Next.js 应用中怎么设置 Tolgee

在这部分中，你将学习如何将Tolgee添加到Next.js应用程序中，并配置以支持多种语言，让用户可以用他们喜欢的语言使用应用程序。

为了在Next.js应用程序中实现本地化，您需要安装这个SDK。

    npm install @tolgee/react

点击全屏 退出全屏

接下来，创建一个Tolgee Platform账号并登录到您的控制面板。

点击项目按钮来新建项目，并选择你需要的语言，比如我们要用五种语言：英语（作为基础），中文，北印度语，西班牙语，阿拉伯语。

（点击这里看看都有哪些语言翻译）

点击右上角的个人资料图标在仪表板上，然后选择"项目API密钥"，为您的Tolgee项目创建一个API密钥。

创建一个名为 .env.development.local 的文件，并将您的 API 秘钥复制到这个文件中。

NEXT_PUBLIC_TOLGEE_API_KEY=在此处粘贴您的API密钥
NEXT_PUBLIC_TOLGEE_API_URL=https://app.tolgee.io

全屏模式 退出全屏

从边栏菜单中选择翻译选项，为项目添加一个新的翻译内容。

你可以创建一个翻译键值，添加你需要翻译的内容或字符串，添加描述，最后保存。

Tolgee 默认提供了多种机器翻译选择，让您轻松地将内容翻译成项目中支持的语言。

恭喜您！您已成功地在应用程序中设置了Tolgee平台。接下来，让我们在Dub.co项目中配置Tolgee，以便可以直接在应用程序中生成翻译内容，使翻译过程更加便捷。

如何在 Dub.co 中设置本地化设置

在这节里，我将带你配置 Tolgee 来支持 Dub.co 项目中的客户端与服务器之间的交互。

首先，安装Tolgee CLI。

npm install --global @tolgee/cli

这将全局安装 tolgee 命令行工具。

进入全屏，退出全屏

运行以下代码段，使用您的API密钥登录到Tolgee。

    tolgee 登录 <your_tolgee_api_key> 命令

进入全屏，退出全屏

请在 apps/web 目录内创建一个 i18n 文件夹。这个文件夹将存放 Tolgee 平台项目中各种语言翻译的 JSON 文件。这里，i18n 是“国际化”的缩写，表示该文件夹将存放不同语言的翻译内容。

    apps
    ├── web #👈 这个文件夹里
        ├── app 
        ├── i18n  #👈 新建
    packages
    ├── tailwind-config
    ├── tinybird
    ├── tsconfig
    ├── ui
    ├── 小工具

进入全屏模式。退出全屏模式。

在 apps/web 文件夹中，运行以下代码片段可以获取你在 Tolgee 项目中创建的语言翻译：

[实际代码片段]

    tolgee --project-id <tolgee_platform_project_id> pull --path ./i18n

点击全屏 点击退出

[]

上面的代码片段会自动填充 i18n 文件夹，这些翻译是在 Tolgee 平台上创建的，包含多种语言。

    apps
    ├── web 
        ├── app 
        ├── i18n #👇🏻 这里是翻译文件
            ├── ar.json
            ├── en.json
            ├── es.json 
            ├── zh.json  
    packages
    ├── tailwind-config
    ├── tinybird
    ├── tsconfig
    ├── ui
    ├── utils

全屏 退出全屏

创建一个名为 tolgee 的文件夹，用于存放 Tolgee 配置，并将其置于 apps/web 目录下。

    应用目录
    ├── web # 👈 这个文件夹（👈）
        ├── app 
        ├── i18n  
        ├── tolgee # 👈 Tolgee 文件夹
    ├── tailwind-config
    ├── tinybird
    ├── tsconfig
    ├── ui
    ├── 工具

切换到全屏模式 退出全屏

在 tolgee 目录下添加一个 shared.ts 文件，然后将以下代码段复制进去：

    import { FormatIcu } from "@tolgee/format-icu";
    import { DevTools, Tolgee } from "@tolgee/react";

    const apiKey = process.env.NEXT_PUBLIC_TOLGEE_API_KEY;
    const apiUrl = process.env.NEXT_PUBLIC_TOLGEE_API_URL;

    //👇🏻 可用的翻译
    export const ALL_LOCALES = ["en", "ar", "es", "zh"];

    //👇🏻 默认语言
    export const DEFAULT_LOCALE = "en";

    //👇🏻 返回包含本地化文件的对象
    export async function getStaticData(languages: string[]) {
      const result: Record<string, any> = {};

      for (const lang of languages) {
        result[lang] = (await import(`../i18n/${lang}.json`)).default;
      }

      return result;
    }

    export function TolgeeBase() {
      return Tolgee().use(FormatIcu()).use(DevTools()).updateDefaults({
        apiKey,
        apiUrl,
        fallbackLanguage: "en",
        defaultLanguage: DEFAULT_LOCALE,
      });
    }

全屏模式 退出全屏

上述代码片段配置了 Tolgee，设置了默认和备用语言，以实现应用程序的本地化。

接下来，请在 tolgee 目录下创建一个 client.tsx 文件，然后将下面的代码片段粘贴到文件中：

    'use client';

    import { TolgeeBase } from './shared';
    import { TolgeeProvider, useTolgeeSSR } from '@tolgee/react';
    import { useRouter } from 'next/navigation';
    import { useEffect } from 'react';

    type Props = {
      locales: any;
      locale: string;
      children: React.ReactNode;
    };

    const tolgee = TolgeeBase().初始化();

    export const TolgeeNextProvider = ({ locale, locales, children }: Props) => {
      const tolgeeSSR = useTolgeeSSR(tolgee, locale, locales);
      const router = useRouter();

      useEffect(() => {
        const { unsubscribe } = tolgeeSSR.on('permanentChange', () => {
          router.refresh();
        });

        return () => unsubscribe();
      }, [tolgeeSSR, router]);

      return (
        <TolgeeProvider
          tolgee={tolgeeSSR}
          options={{ useSuspense: false }}
          fallback="正在加载"
        >
          {children}
        </TolgeeProvider>
      );
    };

切换到全屏模式，退出全屏

client.tsx 文件的作用是翻译客户端组件的内容，并且为服务器渲染的组件提供上下文功能。下面的代码定义了 TolgeeNextProvider 组件，该组件包裹整个Dub.co应用，提供管理语言变化和翻译所需的配置。

在 tolgee 文件夹中创建一个名为 locale.ts 的自定义文件，并将以下代码片段复制进去：

    "use server";

    import { cookies, headers } from "next/headers";
    import { ALL_LOCALES, DEFAULT_LOCALE } from "./shared.ts";

    const COOKIE_NAME = "NEXT_LOCALE";

    //👇🏻 获取用户的当前语言设置：如果未设置，则尝试根据浏览器偏好检测用户的语言。
    // 默认情况下，如果没有匹配项，则使用应用程序的默认本地化设置。
    export async function getUserLocale() {
      return (
        cookies().get(COOKIE_NAME)?.value || detectLanguage() || DEFAULT_LOCALE
      );
    }

    //👇🏻 将用户的首选语言设置为 cookie，以持久化其选择。
    export async function setUserLocale(locale: string) {
      cookies().set(COOKIE_NAME, locale);
    }

    //👇🏻 尝试根据浏览器设置检测用户的首选语言。
    const detectLanguage = () => {
      const allPreferred = getAcceptedLanguages();

      for (const language of allPreferred) {
        // 检查是否在支持的语言列表中存在精确匹配的语言
        const exactMatch = ALL_LOCALES.find((l) => l === language);
        if (exactMatch) {
          return exactMatch;
        }

        // 回退到仅匹配两个字母的语言代码以进行匹配
        const getTwoLetters = (fullTag: string) =>
          fullTag.replace(/^(.+?)(-.*)?$/, "$1");

        const preferredTwoLetter = getTwoLetters(language);
        const twoLetterMatch = ALL_LOCALES.find(
          (l) => getTwoLetters(l) === preferredTwoLetter,
        );
        if (twoLetterMatch) {
          return twoLetterMatch;
        }
      }
    };

    //👇🏻 从 "Accept-Language" HTTP 头中检索接受的语言。
    // 返回按偏好顺序排列的语言列表。
    function getAcceptedLanguages() {
      const acceptLanguageHeader = getAcceptLanguageHeader();
      if (!acceptLanguageHeader) {
        return [];
      }

      // 通过逗号分隔每个语言代码来拆分头值以进行处理
      return acceptLanguageHeader.split(",").map((lang) => {
        const [language] = lang.split(";");
        return language.trim();
      });
    }

    //👇🏻 从用户的浏览器中获取 "Accept-Language" HTTP 头。
    // 此头列出了用户偏好的语言，按偏好顺序排列。
    function getAcceptLanguageHeader() {
      return headers().get("Accept-Language");
    }

切换到全屏和退出全屏

接下来，在 tolgee 文件夹中创建一个名为 server.tsx 的文件，然后将以下代码片段复制到文件中：

    import { getUserLocale } from "./locale.ts";
    import { TolgeeBase, ALL_LOCALES, getStaticData } from './shared';
    import { createServerInstance } from '@tolgee/react/server';

    export const { getTolgee, getTranslate, T } = createServerInstance({
       getLocale: async () => getUserLocale(),
      createTolgee: async (locale) =>
        TolgeeBase().init({
          // 包含所有语言环境
          // 在服务器端，我们不关注包的大小
          staticData: await getStaticData(ALL_LOCALES),
          observerOptions: {
            fullKeyEncode: true,
          },
          language: locale,
          fetch: async (input, init) => {
            const data = await fetch(input, { ...init, next: { revalidate: 0 } });
            return data;
          },
        }),
    });

进入全屏。退出全屏。

该应用程序使用 React 服务器缓存，实现在单次渲染过程中跨组件共享 Tolgee 实例。这使得应用程序可以在任何服务器组件中使用 Tolgee 实例。

恭喜您！您已成功设置了 Tolgee，现在可以开始翻译应用里的不同内容。

---

如何用Tolgee翻译您的应用内容

在这里，你将学习如何在你的 web 应用中翻译网页内容，并了解 Tolgee 如何让你轻松地进行内建翻译。

首先，你需要用 TolgeeNextProvider 组件包裹整个 Dub.co 应用程序，该组件在 tolgee/client.tsx 文件中定义。导航到 apps/web/app 文件夹，然后进入 app.dub.co/(dashboard) 目录，然后按照下面的方式更新 layout.tsx 文件：

    import { MainNav } from "@/ui/layout/main-nav";
    import { HelpButtonRSC } from "@/ui/layout/sidebar/help-button-rsc";
    import Toolbar from "@/ui/layout/toolbar/toolbar";
    import { constructMetadata } from "@dub/utils";
    import { ReactNode } from "react"; // 导入 React 节点
    import Providers from "../../providers";
    //👇🏻 Tolgee 相关导入
    import { TolgeeNextProvider } from "../../../tolgee/client.tsx";
    import { getUserLocale } from "../../../tolgee/locale.ts";
    import { getStaticData } from "../../../tolgee/shared.ts";

    export const metadata = constructMetadata(); // 元数据（元数据定义）

    export default async function Layout({ children }: { children: ReactNode }) {
      const locale = await getUserLocale();
      const locales = await getStaticData([locale, "en"]);

      return (
        <TolgeeNextProvider locale={locale} locales={locales}>
          <Providers>
            <div className="min-h-screen w-full bg-white">
              <MainNav toolContent={<HelpButtonRSC />}>{children}</MainNav>
            </div>
            {/* <版本变更弹窗 /> */}
            <Toolbar show={["引导"]} /> {/* 显示引导页面 */}
          </Providers>
        </TolgeeNextProvider>
      );
    }

全屏模式 退出全屏

上面的代码片段将仪表板路由包裹在 Tolgee 提供程序中，实现了语言切换和本地化功能，在整个应用中。

Tolgee 提供了两个钩子来帮助你在应用中选择和翻译文本，：useTolgee 和 useTranslate。

• useTolgee 钩子返回 Tolgee 实例，允许你订阅各种事件，这些事件会在翻译过程中自动触发重新渲染。
• useTranslate 钩子提供了 t 函数，该函数可以在应用中渲染实际的翻译内容。

在 app.dub.co/(dashboard)/[slug] 目录下的 page.tsx 文件中，加入如下代码片段：

"use client";
import { PageContent } from "@/ui/layout/page-content";
import WorkspaceLinksClient from "./page-client";
//👇🏻 Tolgee 集成
import { useTolgee, useTranslate } from "@tolgee/react";
import { setUserLocale } from "tolgee/locale";

export default function WorkspaceLinks() {
  const { t } = useTranslate();
  const tolgee = useTolgee(["pendingLanguage"]);
  const language = tolgee.getPendingLanguage();

  return (
    <PageContent title="链接页面">
    {/** -- 选择语言的 HTML 输入 -- */}
      <div className="flex w-full flex-col px-10">
        <p>选择语言</p>
        <select
          defaultValue={language}
          className="rounded-sm"
          name="locale"
          id="locale"
          onChange={(e) => setUserLocale(e.currentTarget.value)}
        >
          <option value="en">英文</option>
          <option value="es">西班牙语</option>
          <option value="ar">阿语</option>
          <option value="zh">中文</option>
        </select>

        <p>{t("你好")}</p>
      </div>
    {/** -- 结束 -- */}
      <WorkspaceLinksClient />
    </PageContent>
  );
}

点击全屏 按钮 点击退出全屏

下面的代码片段展示了一个 HTML <select> 标签，让用户可以切换不同的语言。{t("hello")} 元素利用 Tolgee 的翻译功能来显示根据选定语言的 'hello' 关键字对应的值。

最后，你可以更新应用程序中的其余内容，以支持语言切换，这样用户就能用他们选的语言来看所有的组件了。

Tolgee 还提供了一个上下文中的翻译功能，允许你直接在应用的任何环境中翻译字符串，只需点击文本并按住 Alt 键（Windows）或 Option 键（Mac）即可。

恭喜你！你完成了这个教程里的项目。

本教程的源代码可以在这里查看/下载：

链接如下：这是一个GitHub仓库链接，指向JanCizmar的dub-with-tolgee项目。https://github.com/JanCizmar/dub-with-tolgee

---

结论部分

到现在为止，你已经学会了如何使用Tolgee将软件应用程序本地化，支持多种语言，并在实际项目中实现无缝的语言切换。

Tolgee 是一个面向开发人员的快速本地化平台，允许你为内容提供上下文，并且可以在几秒钟内生成翻译。它还支持如 Vue、Angular 和 Svelte 在内的多个 JavaScript 框架，并集成与 Figma 和 REST API 等，以增强灵活性的工具。

如果你想为用户提供个性化的体验，Tolgee 是一个很好的选择。欢迎为我们的 GitHub 仓库 贡献和点赞，加入我们的 Slack 社区，与他人连接并与团队互动。

非常感谢您的耐心阅读！