Nextjs——国际化那些事儿

最新推荐文章于 2024-08-09 08:13:59 发布

just小千

最新推荐文章于 2024-08-09 08:13:59 发布

阅读量1.1k

点赞数 18

分类专栏： Next 文章标签：前端 typescript next 国际化

本文链接：https://blog.csdn.net/weixin_43207208/article/details/140568221

版权

Next 专栏收录该内容

3 篇文章 1 订阅

订阅专栏

背景：某一天，产品经理跟我说，我们的产品需要搞国际化

国际化的需求说白了就是把项目中的文案翻译成不同的语言，用户想用啥语言来浏览网页就用啥语言，虽然说英语是通用语言，但国际化了嘛，产品才能更好的向全球推广（像我这种英文渣渣，看文档的时候有中文版绝对不会去翻英文（除非中文翻译得太烂））。那就开干吧

国际化在代码层面的实现上原理其实很简单，最基础的是准备好语言物料，也就是需要翻译成多少种语言，保证项目中每种语言都有对应的翻译版本，然后就是用户选择什么语言，页面就显示对应的文案，完美～

1. 用户自己解决

如果用户有翻译插件，那问题就会变得很简单，点开页面，翻译软件就能自动识别文案并翻译，没我们什么事，在chrome浏览器中，google translate就做得很好，打开很多页面的时候，google translate都能识别当前语言和系统语言是否一致，并且提供翻译提醒。但是……google translate也不是万能的，next.js网站中，使用google translate会导致网站崩溃，但后来人家也说了，这不是next的锅，锅在react那，并且已持续多年。
issue传送：Make React resilient to DOM mutations from Google Translate
google translate的兼容性都那么不好，其他的翻译插件兼容性如何也就成了未知数，为了网站的稳定性，减少网站崩溃次数，建议在head中关闭翻译功能。

<meta name="google" content="notranslate" />

2. 第三方SaaS

既然不能靠用户，那就只能自己来了，那有没有开发成本小，低代码或者零代码就能实现呢？世界人民如此聪明，当然有了。现在市面上有很多成熟的SaaS国际化软件，当时经过各种比较之后选了Weglot添加链接描述进行测试（不是广告，比较之后发现它比较好上手而已）。它的原理也比较简单：获取页面上它觉得需要进行翻译的元素，通过接口将翻译之后的内容返回并在页面上进行替换，具体的操作步骤如下：

1. 在网站内注册，创建自己的项目，把js代码以及项目的key注入代码

// useWeglot
// 在最外层的layout或者是需要国际化的目录的根文件中使用
"use client";

import { useEffect } from "react";

export default function useWeglot() {
  useEffect(() => {
    const initializeWeglot = () => {
      if (typeof window?.Weglot !== "undefined") {
        window?.Weglot.initialize({
          api_key: "这里写你的key", 
          originalLanguage: "en",
          auto_switch_fallback: "zh",
        });
      }
    };

    const loadWeglotScript = () => {
      const existingScript = document.getElementById("weglot-script");
      if (!existingScript) {
        const script = document.createElement("script");
        script.id = "weglot-script";
        script.src = "https://cdn.weglot.com/weglot.min.js";
        script.async = true;
        script.onload = initializeWeglot;
        document.body.appendChild(script);
      } else {
        initializeWeglot();
      }
    };
    loadWeglotScript();
  }, []);

  return null;
}

在这里插入图片描述

1. 自定义规则，将需要翻译和不需要翻译的部分都用规则标记上（比如class），这样翻译时它就能避开一些本来不需要翻译的部分，比如接口返回的数据
1. 微调，默认都是机翻，有些翻译得不是很通顺的地方可以人工调整
  
  如果是简单的项目，它还是很好用的，代码侵入性小，翻译之后的文本也全部都维护到weglot里，通过接口返回，需要翻译修改时直接在网站中改完实时更新，特别省事。
  但缺点也是显而易见的，首先，它免费额度不太大，项目比较大，涉及语言比较多的话价格也不便宜；其次，因为是接口返回的翻译内容，用户第一次进入页面时会先出现原本的语言，再跳到对应的语言，首次加载会闪下（可能有优化方案，知道的朋友踢我下）；而且因为是代码读取元素内容，很有可能出现多翻译或者少翻的情况，在实际开发中调试也需要一定时间。

3. 自己开发

啰里八嗦了一大堆终于到了正题，经过了一系列的研究和探讨，最终决定了，自己开发！！！代码开发最主要是确认两个问题，一是系统要如何获取语言，二是系统如何跟翻译好的文本进行交互，这两个问题解决完，国际化也就完成了大半。

如何获取语言

世界上有很多很多的语言种类，国际上对语言有一个编码规范（ISO 639，有兴趣的可以了解下，比如简体中文为啥有些地方直接写zh，有时候是zh-CN），在编码的时候，也是遵循这套标准定义，规范好了，那通过什么方式告诉系统，当前是什么语言呢？通常有以下两种：

Google 建议对每种语言版本的网页使用不同的网址，而不是使用 Cookie 或浏览器设置来调整网页上的内容语言。

1. 路由
- 通过host获取，比如维基百科：https://zh.wikipedia.org/
- 放在pathname中，比如MDN：https://developer.mozilla.org/zh-CN/docs/Web/JavaScript
- 放在参数中，比如google开发者平台：https://developers.google.com/?hl=zh-cn
  google 对国际化网站有一些建议：
1. 缓存(cookie或者localStorage)
  从上面来看就是google不太推荐用这种形式，但它在实现上相对简单，只需要存在浏览器本地，运行时读取浏览器数据，渲染出对应的语言信息。需要注意的是，如果后端接口也需要国际化（比如一些接口报错啥的），可以使用cookie，但cookie会涉及数据隐私问题（欧盟标准），一旦用户选择不使用cookie，就不能通过cookie进行语言的切换。

如何进行翻译文本的交互

不管什么形式获取的语言，最后反应到系统程序上都是一个语言代码的形式，用户通过获取这个语言代码，将代码匹配到对应的翻译文本中，就能将对应语言的文案展示出来了。
为了方便，接下来所有文本都以这两个json文件为例：

// dictionaries/en.json
{
	"title":"hello world",
	"desc": {
		name:"xiaoqian"
	}
}

// dictionaries/zh.json
{
	"title":"你好",
	"desc": {
		name:"小千"
	}
}

// i18n-config.ts
export const i18n = {
    defaultLocale: 'en',
    locales: ['en', 'zh'],
  } as const
  
export type Locale = (typeof i18n)['locales'][number]


//  get-dictionary.ts
import type { Locale } from './i18n-config'

// 翻译之后的文本分别保存在dictionaries/en.json 以及dictionaries/zh.json中
const dictionaries = {
  en: () => import('./dictionaries/en.json').then((module) => module.default),
  zh: () => import('./dictionaries/zh.json').then((module) => module.default),
}

export const getDictionary = async (locale: Locale) =>
  dictionaries[locale]?.() ?? dictionaries.en()


// useDict
"use client";
import { useState,useEffect, useCallback,  } from "react";
import { getDictionary } from "@/get-dictionary";
import { Locale } from "@/i18n-config";

const lang = process.env.NEXT_PUBLIC_LANG as Locale;

export default function useDict() {
  const [desc, setDesc] = useState<any>({});

  const getDict = useCallback(async () => {
    const locale = await getDictionary(lang);
    setDesc(locale);
  }, []);

  useEffect(() => {
    getDict();
  }, [getDict]);
  return desc
}

// page.tsx
import useDict from "@/hook/useDict"

export default function Page(){
	const lang = useDict()
return <div>{lang?.desc?.name}</div>
}

这样一个最简单的国际化配置就完成了，不同语言不同域名的场景下可以使用这种配置，每种语言打一个包，部署在不同域名下，好处是不需要添加额外的包，缺点是比较不灵活，比较适合语言不是很多，文字不复杂的情况，一些复杂的场景不好处理。

next-intl

需要处理复杂场景的时候，使用库是最快乐的选择，因为我们想得到想不到的场景它都已经实现了，next官方推荐了三个库next-intl,next-international以及next-i18n-router，按照活跃度和文档可读性等等，我选择使用next-intl，以下的代码也都是在这个库的基础上实现的
老规矩，先上官方文档：https://next-intl-docs.vercel.app/
文档里有page-router以及app-router的实现方式，这里以app-router为例子（因为我就是那个用app-router写代码的大怨种呜呜呜），涉及多种场景，接下来就一一拆解吧～

场景一：使用cookie
总有那么一群人因为各种各样的原因需要使用cookie辅助语言的切换，对国际化配置而言，更人性化的是先检测浏览器语言（因为浏览器语言大概率是用户最常用的语言），根据浏览器语言设置默认语言，这时候需要使用到middleware.ts

// middleware.ts
import { match as matchLocale } from "@formatjs/intl-localematcher";
import Negotiator from "negotiator";
import type { NextRequest } from "next/server";
import { NextResponse } from "next/server";

import { defaultLocale, locales } from "@/utils/i18n";

function getLocale(request: NextRequest): string | undefined {
  const locale = request.cookies.get("xiaoqian-locale");
  // 如果cookie中有预设的国际化值，则返回该值
  if (locale) {
    return locale.value;
  }
  // Negotiator expects plain object so we need to transform headers
  const negotiatorHeaders: Record<string, string> = {};
  // eslint-disable-next-line no-return-assign
  request.headers.forEach((value, key) => (negotiatorHeaders[key] = value));

  // Use negotiator and intl-localematcher to get best locale
  const languages = new Negotiator({ headers: negotiatorHeaders })?.languages();

  let loc = "";

// matchLocale可能会报错，需要用try catch包括，确保在匹配不上语言时使用默认语言而不是直接报错
  try {
    loc = matchLocale(languages, locales, defaultLocale);
  } catch (error) {
    loc = defaultLocale;
  }

  return loc;
}

export function middleware(request: NextRequest) {
  const locale = getLocale(request);
  const response = NextResponse.next();
  // 执行了setcookie之后，所有的缓存会被清空
  response.cookies.set("xiaoqian-locale", locale as string);
  return response;
}

对应的i8n配置和之前的版本也很类似

import { getRequestConfig } from "next-intl/server";

export const defaultLocale = "en" as const;
export const locales = [
  "en",
  "zh",
] as const;

export type Locale = (typeof locales)[number];

export default getRequestConfig(async () => {
  // Provide a static locale, fetch a user setting,
  // read from `cookies()`, `headers()`, etc.
  const { cookies } = await import("next/headers");
  const cookieStore = cookies();
  const lang = cookieStore.get("xiaoqian-locale");
  const locale = lang?.value || "en";
  // const locale = "en";

  return {
    locale,
    messages: (await import(`../../dictionaries/${locale}.json`)).default,
  };
});

使用方法很简单

// use client
import {useTranslations} from 'next-intl'

export default function Page(){
// 可以使用命名空间，就不需要些一连串的(a.b.c.d)了
	const t = useTranslations("desc")
	return <div>{t("name")}</div> // = desc.name
}

// use server
import { getLocale, getTranslations } from "next-intl/server";

export default function Page(){
	const locale = await getLocale();
  	const t = await getTranslations({ locale, namespace: "desc" });
	return <div>{t("name")}</div> // = desc.name
}

深度用法：https://next-intl-docs.vercel.app/docs/usage/messages

场景二：以子目录的形式
复习一下，子目录也就是xiaoqian.com/en/xxx，xiaoqian.com/zh/xxx这种形式，其实这种形式也使用了cookie（NEXT_LOCALE），比起第一种场景的好处是，cookie的存储过程next-intl已经处理完毕，不需要我们操心

import createMiddleware from 'next-intl/middleware';

import { localePrefix,defaultLocale, locales,pathnames } from './utils/i18n';
 
export default createMiddleware({
    defaultLocale,
    locales,
    localePrefix,
    alternateLinks: false, // 默认语言不需要加子目录时需要加上这个配置
    pathnames,
});


  export const config = {
    matcher: [
      "/",
      `/(en|zh)/:path*`,
      "/((?!api|_next|_vercel|.*\\..*).*)",
    ],
  };

一些配置文件

// i18n.ts

import {notFound} from 'next/navigation';
import {getRequestConfig} from 'next-intl/server';
import {Pathnames, LocalePrefix} from 'next-intl/routing';

export const defaultLocale = 'en' as const;
export const locales = ['en', 'zh'] as const;

export const pathnames: Pathnames<typeof locales> = {
  '/': '/',
  '/channels': {
    'en': '/channels',
    'zh': '/channels',
  }
};

export const localePrefix: LocalePrefix<typeof locales> = 'as-needed'; 
// 默认语言不需要加子目录时需要加上这个配置
// 比如默认中文：xiaoqian.com/xxx， 切换成英文才需要xiaoqian.com/en/xxx

export type Locale = (typeof locales)[number];
 
export default getRequestConfig(async ({locale}) => {
  // Validate that the incoming `locale` parameter is valid
  if (!locales.includes(locale as any)) notFound();
 
  return {
    messages: (await (locale === 'en'
    ? // When using Turbopack, this will enable HMR for `en`
      import('../../dictionaries/en.json')
    : import(`../../dictionaries/${locale}.json`))).default
  };
});


// navigation.ts
import {createLocalizedPathnamesNavigation} from 'next-intl/navigation';
import {locales, pathnames, localePrefix} from './i18n-config';

export const {Link, getPathname, redirect, usePathname, useRouter} =
  createLocalizedPathnamesNavigation({
    locales,
    pathnames,
    localePrefix
  });

使用时会稍微复杂一点点

路由需要进行配置，代码结构需要类似这种：
2.
路由切换时需要使用声明的Link而不是原生Link

import {Link} from "@/utils/i18n/navigation";
import {useTranslations} from 'next-intl';


export default function Home() {
 const t = useTranslations()
  return (
    <main>
      <div>
      {t("desc.name")}
      </div>
      <Link href="/channels">Channels</Link>
    </main>
  );
}

其他场景
next-intl最好的地方就是它给的例子多啊多啊多，上述两种场景是我为了满足需求修改过的代码，普通场景下的代码网站中都有详细的示例以及源码，示例地址：https://next-intl-docs.vercel.app/examples，请按需使用。

温馨提示

到这里，国际化开发的基本步骤就拆解完了，之前一直觉得配置完就完事了，美滋滋，但实际对代码进行修改的时候才发现，一个个手动改文案翻译文案太痛苦了，next-intl也很贴心的给了两个vscode插件用来进行国际化的检查和翻译，极大增强了工作效率和幸福感，工具果然是提高效率的第一生产力。如果是多人协作开发的话，对于json文件，可以考虑用排序插件（比如Sort JSON），提交之前先排个序，防止代码冲突