作為與Tolgee合作的一部分，我嘗試將 dub.co（一家成熟的開源公司）翻譯成其他語言！我花了1個小時，結果令人驚訝！

在本教程中，我將引導您使用Tolgee （專為快速、自主翻譯管理而設計的平台）在 Next.js 應用程式中實作簡單且高效的在地化方法。

您還將學習如何將 Tolgee 與Dub.co集成，Dub.co 是一個流行的連結管理平台，允許用戶以其首選語言存取應用程式並與之互動。

先決條件

要完全理解本教程，您需要對 React 或 Next.js 有基本的了解。

您還需要設定以下內容：

• Tolgee 專案- 至少有兩種語言翻譯的現有專案。

• Tolgee CLI - 允許您使用命令列從電腦與 Tolgee 平台進行互動。

• Docker - 執行 Dub.co 所必需的。它是一個開源平台，使用容器化來更輕鬆地建立、部署和執行應用程式。

• Docker Compose - 用於定義和執行多容器 Docker 應用程式的軟體應用程式。

• Python（版本 3.8 或更高版本） ：配置 Dub.co 的某些軟體包所必需的。

托爾吉是什麼？

Tolgee 是一個開發人員友好的在地化平台，可讓您將應用程式翻譯成任何語言，而無需修改程式碼。它專為 Web 應用程式設計，但也支援行動和桌面應用程式。

使用 Tolgee，您無需在原始程式碼中尋找金鑰、編輯在地化檔案或為翻譯人員執行手動匯出資料。 Tolgee 提供上下文翻譯、用於追蹤已翻譯字串的翻譯記憶庫、機器和自動翻譯等。

請幫我們加一顆星。 🥹

這將幫助我們建立更多這樣的文章💖

{% cta https://tolg.ee/t3r2db %}為 Tolgee 儲存庫加註星標 ⭐{% endcta %}

如何在本地電腦上設定 Dub.co

Dub.co 是一個開源連結管理平台，允許行銷團隊為其連結加入強大的分析功能、建立短連結、為連結產生二維碼等等。它是由 Steven Tey（前 Vercel 公司）建立的。

請依照以下步驟在您的電腦上設定 Dub.co：

透過執行下面的程式碼片段來克隆Dub.co GitHub 儲存庫。

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

導航至dub資料夾並安裝專案依賴項：

pnpm install

在apps/web資料夾中，將.env.example檔案重新命名為.env 。

建立一個新的Tinybird 帳戶，並將您的Admin Auth Token令牌複製到.env檔案中。

TINYBIRD_API_KEY=<your_admin_auth_token>

導覽至packages/tinybird目錄並使用以下指令安裝 Tinybird CLI：

pip3 install tinybird-cli

在終端機中執行以下命令，並在提示使用 Tinybird CLI 進行身份驗證時輸入您的管理員身份驗證令牌：

tb auth

透過執行以下程式碼片段來發布 Tinybird 資料來源和端點：

tb push

建立Upstash 資料庫並將下列憑證從 REST API 部分複製到.env檔：

UPSTASH_REDIS_REST_URL=<your_rest_url>
UPSTASH_REDIS_REST_TOKEN=<your_rest_token>

導覽至QStash 標籤並將下列憑證複製到.env檔案中。

QSTASH_TOKEN=
QSTASH_CURRENT_SIGNING_KEY=
QSTASH_NEXT_SIGNING_KEY=

接下來，在apps/web目錄中，執行以下命令來啟動 Docker Compose 堆疊：

docker-compose up

使用以下命令產生 Prisma 用戶端並建立其資料庫表：

npx prisma generate
npx prisma db push

Dub.co 支援多種身份驗證方法。建立一個 GitHub 應用程式並複製下面的 URL 作為其回調 URL。

http://localhost:8888/api/auth/callback/github

最後，啟動開發伺服器：

pnpm dev

您可以透過在瀏覽器中導航到http://localhost:8888來存取 Web 應用程式，建立工作區並開始使用。如果您遇到任何問題，請參閱完整的安裝指南以獲得更詳細的協助。

如何在 Next.js 應用程式中配置 Tolgee

在本部分中，您將了解如何將 Tolgee 新增至 Next.js 應用程式並將其配置為支援多種語言，從而允許使用者以其首選語言存取應用程式。

要在 Next.js 應用程式中實現本地化，您需要安裝Tolgee React SDK 。

npm install @tolgee/react

接下來，建立一個Tolgee 平台帳戶並登入您的儀表板。

點擊“專案”按鈕並選擇專案的首選語言來新增專案。對於此應用程式，我們將使用五種語言：英語（作為基本語言）、中文、印地語、西班牙語和阿拉伯語。

點擊儀表板右上角的設定檔圖標，然後選擇專案 API 金鑰為您的 Tolgee 專案建立 API 金鑰。

建立.env.development.local並將您的 API 金鑰複製到該文件中：

NEXT_PUBLIC_TOLGEE_API_KEY=<paste_your_API_key_here>
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

執行以下程式碼片段以使用您的專案 API 金鑰登入您的 Tolgee 平台。

tolgee login <your_tolgee_api_key>

接下來，在apps/web目錄中建立一個i18n資料夾。該資料夾將儲存 JSON 文件，其中包含 Tolgee 平台專案中可用的各種語言的翻譯。

apps
├── web #👈🏼 this folder
    ├── app 
    ├── i18n  #👈🏼 newly created 
packages
├── tailwind-config
├── tinybird
├── tsconfig
├── ui
├── utils

在apps/web目錄中，透過執行以下程式碼片段來取得在 Tolgee 專案中建立的語言翻譯：

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

上面的程式碼片段會自動使用在 Tolgee 平台中建立的各種語言翻譯填滿i18n資料夾。

apps
├── web 
    ├── app 
    ├── i18n #👇🏻 translation files
        ├── ar.json
        ├── en.json
        ├── es.json 
        ├── zh.json  
packages
├── tailwind-config
├── tinybird
├── tsconfig
├── ui
├── utils

在apps/web目錄中建立一個tolgee資料夾，其中包含 Tolgee 配置：

apps
├── web # 👈🏼 this folder
    ├── app 
    ├── i18n  
    ├── tolgee # 👈🏼 Tolgee folder
packages
├── tailwind-config
├── tinybird
├── tsconfig
├── ui
├── utils

在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;

//👇🏻 available translations
export const ALL_LOCALES = ["en", "ar", "es", "zh"];

//👇🏻 default translation
export const DEFAULT_LOCALE = "en";

//👇🏻 returns an object containing the translation files
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().init();

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="Loading"
    >
      {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";

//👇🏻 Retrieves the current language setting for the user.
// If not set, it attempts to detect the user's language from browser preferences.
// Defaults to the application's default locale if no match is found.
export async function getUserLocale() {
  return (
    cookies().get(COOKIE_NAME)?.value || detectLanguage() || DEFAULT_LOCALE
  );
}

//👇🏻 Sets the user’s preferred language in a cookie to persist their selection.
export async function setUserLocale(locale: string) {
  cookies().set(COOKIE_NAME, locale);
}

//👇🏻 Attempts to detect the user's preferred language based on browser settings.
const detectLanguage = () => {
  const allPreferred = getAcceptedLanguages();

  for (const language of allPreferred) {
    // Checks for an exact match in the list of supported locales
    const exactMatch = ALL_LOCALES.find((l) => l === language);
    if (exactMatch) {
      return exactMatch;
    }

    // Falls back to matching only the two-letter language code
    const getTwoLetters = (fullTag: string) =>
      fullTag.replace(/^(.+?)(-.*)?$/, "$1");

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

//👇🏻 Retrieves accepted languages from the "Accept-Language" HTTP header.
// Returns an array of languages in order of preference.
function getAcceptedLanguages() {
  const acceptLanguageHeader = getAcceptLanguageHeader();
  if (!acceptLanguageHeader) {
    return [];
  }

  // Splits the header value by commas to separate each language code
  return acceptLanguageHeader.split(",").map((lang) => {
    const [language] = lang.split(";");
    return language.trim();
  });
}

//👇🏻 Fetches the "Accept-Language" HTTP header from the user's browser.
// This header lists languages preferred by the user, ranked by preference.
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({
      // including all locales
      // on server we are not concerned about bundle size
      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 如何實現輕鬆的應用程式內翻譯。

首先，您需要使用tolgee/client.tsx中定義的TolgeeNextProvider元件包裝整個 Dub.co 應用程式。導航到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";
import Providers from "../../providers";
//👇🏻 Tolgee imports
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>
        {/* <ChangelogPopup /> */}
        <Toolbar show={["onboarding"]} />
      </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 installations
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="Links">
    {/** -- HTML input for selecting the preferred language -- */}
      <div className="flex w-full flex-col px-10">
        <p>Select Language</p>
        <select
          defaultValue={language}
          className="rounded-sm"
          name="locale"
          id="locale"
          onChange={(e) => setUserLocale(e.currentTarget.value)}
        >
          <option value="en">English</option>
          <option value="es">Spanish</option>
          <option value="ar">Arabic</option>
          <option value="zh">Chinese</option>
        </select>

        <p>{t("hello")}</p>
      </div>
    {/** -- end of Tolgee -- */}
      <WorkspaceLinksClient />
    </PageContent>
  );
}

上面的程式碼片段顯示了一個 HTML <select>標記，允許使用者選擇並在不同語言之間切換。 {t("hello")}元素使用 Tolgee 的翻譯函數根據所選語言呈現「hello」鍵的值。

最後，您可以更新整個應用程式中的剩餘內容以支援語言更改，從而允許使用者以所選語言查看所有元件。

Tolgee 還提供上下文翻譯功能，讓您可以直接在應用程式中翻譯字串，無論是在開發還是生產中，只需單擊文字並按住 Alt 或 Option 鍵即可。

恭喜！您已成功完成本教學的專案。

本教學的源程式碼可在此處取得：

https://github.com/JanCizmar/dub-with-tolgee

結論

到目前為止，您已經學習瞭如何使用 Tolgee 將本地化加入到您的軟體應用程式中，實現對多種語言的支持，以及如何在實際專案中實現語言無縫切換。

Tolgee 是一個快速、以開發人員為中心的在地化平台，可讓您為內容提供上下文並在幾秒鐘內產生翻譯。它還支援多種 JavaScript 框架，包括 Vue、Angular 和 Svelte，並與 Figma 和 REST API 等工具整合以實現靈活性。

如果您希望為使用者建立個人化體驗，Tolgee 是一個絕佳的選擇。請隨意為我們的GitHub 儲存庫做出貢獻並加註星標，並加入我們的Slack 社群以與其他人聯繫並與團隊互動。

感謝您的閱讀！

原文出處：https://dev.to/tolgee_i18n/i-have-localized-the-best-short-linking-platform-in-the-world-344l