企业官网建设流程全解析

• 低代码
• 前端
• 后端

本文基于 Plasmic 开源仓库中的nextjs-i18n-i18next示例项目，讲解如何将 Plasmic 可视化构建的页面接入next-i18next国际化框架。读完本文，你将掌握：通过 CLI 命令将 Plasmic Studio 项目中的文案一键导出为 JSON 消息文件、为多语言维护翻译文件、用 i18next 原语编写PlasmicTranslator并注入PlasmicRootProvider，最终实现基于 Next.js 路由 locale 的多语言页面。

示例项目概览

nextjs-i18n-i18next是一个完整的 Next.js 应用，演示了 Plasmic i18n 与 next-i18next 的集成方式。整个示例的 i18n 相关代码集中在四个文件中：

• pages/_app.tsx：用next-i18next的appWithTranslation()包装整个App；
• i18n.tsx：定义usePlasmicTranslator()，基于 i18next 原语（t与<Trans>）实现翻译函数；
• pages/index.tsx：调用usePlasmicTranslator()创建 translator，并传入<PlasmicRootProvider />；
• next-i18next.config.js：按 next-i18next 官方脚手架配置语言列表与默认语言。

工作流分为两步：先运行npm run plasmic-i18n把 Plasmic 项目中的文本消息导出到public/locales/en/common.json，再在public/locales/X/common.json中为其他语言补充翻译。对应演示项目的 Plasmic Studio 工程 ID 为fjKQstuhKKVhuH5dkNkNtj，可在 plasmic-init.ts 中看到加载器的初始化配置。

一、配置 next-i18next：语言表与 Next.js 路由国际化

1. next-i18next 配置

next-i18next.config.js 定义了项目支持的语言范围：

module.exports = { i18n: { defaultLocale: "en", locales: ["en", "es"], }, };

这里声明了默认语言en与可用语言列表["en", "es"]（英语、西班牙语）。后续需要新增语言（例如法语fr）时，只需在此列表中加入语言代码，并在public/locales/fr/common.json提供对应翻译文件。

2. 将 i18n 配置接入 Next.js

next.config.js 把上述 i18n 配置透传给 Next.js 的国际化路由机制：

const { i18n } = require("./next-i18next.config"); /** @type {import('next').NextConfig} */ const nextConfig = { reactStrictMode: false, i18n, }; module.exports = nextConfig;

配置之后，Next.js 会为/生成/en、/es等 locale 前缀路由，并通过useRouter()暴露router.locale，供页面判断当前语言。这正是后续语言切换按钮动态渲染color属性的依据。

二、导出 Plasmic 项目文案：npm run plasmic-i18n

1. 命令入口

示例在 package.json 中预置了导出脚本：

"scripts": { "dev": "next dev", "build": "next build", "start": "next start", "lint": "next lint", "plasmic-i18n": "plasmic localization-strings --output public/locales/en/common.json --format=json --force-overwrite --projects=fjKQstuhKKVhuH5dkNkNtj" }

2. 命令参数解析

该脚本调用了@plasmicapp/cli（示例中版本为^0.1.203，实现位于 packages/cli/src）的localization-strings子命令，各参数含义如下：

运行npm run plasmic-i18n后，Plasmic 页面中所有绑定到本地化 key 的文本会以「key → 英文文案」的映射写入public/locales/en/common.json。

3. 导出产物的结构

public/locales/en/common.json 展示了导出结果：每个 key 即页面中的原始文本，value 为对应语言的翻译。值得注意的是一条富文本示例：

"Welcome to the new <1>technology</1> of the <2>future</2>."

key 与 value 中带有<1>、<2>数字占位符，这是 Plasmic 富文本（Rich Text）的标记方式——占位符对应文本中内嵌的组件（如链接、加粗段落）。翻译时必须保留这些占位符编号，翻译器才能把相应 React 组件插回正确位置。

三、为其他语言添加翻译

导出英文文件后，将common.json复制到其他语言目录并逐一翻译即可。示例仓库已内置西班牙语翻译 public/locales/es/common.json，例如：

{ "Welcome to the new <1>technology</1> of the <2>future</2>.": "Bienvenido a la nueva <1>tecnología</1> del <2>futuro</2>.", "Check out this i18n demo!! It also works with <1>RICH TEXT</1> and <2>links</2>!": "¡Mira esta demostración de i18n! ¡También funciona con <1>TEXTO ENRIQUECIDO</1> y <2>enlaces</2>!", "English": "Inglés", "Try demo for free": "Pruebe la demostración gratis", "Spanish": "Español", "Learn More": "Aprende más" }

翻译时注意两点：占位符<1>、<2>必须原样保留；未翻译的 key 可以保留英文原值（示例中的 footer 文案即如此），i18next 会回退到 key 本身。目录结构public/locales/<locale>/common.json是 next-i18next 的约定路径，serverSideTranslations(locale)会按此加载。

四、编写翻译器：usePlasmicTranslator()

1. PlasmicTranslator 的类型契约

Plasmic 通过PlasmicRootProvider的translatorprop 接入任意 i18n 框架。其类型定义位于 packages/loader-react/src/PlasmicRootProvider.tsx：

export type PlasmicTranslator = ( str: string, opts?: { components?: { [key: string]: React.ReactElement | React.ReactFragment; }; } ) => React.ReactNode;

翻译函数接收两个参数：待翻译的字符串 key，以及可选的components映射——当 Plasmic 渲染富文本时，会把内嵌组件按占位符编号（如<1>、<2>）作为 React 元素传入。返回值是ReactNode，意味着富文本翻译可以返回包含组件的 JSX。

2. 基于 i18next 的实现

i18n.tsx 给出了完整实现：

import { PlasmicTranslator } from "@plasmicapp/loader-nextjs"; import { Trans, useTranslation } from "next-i18next"; import React from "react"; export function usePlasmicTranslator() { const { t } = useTranslation(); const translator: PlasmicTranslator = (key, opts) => { if (opts?.components) { return ( <Trans i18nKey={key} components={opts.components as Record<string, React.ReactElement>} /> ); } else { return t(key); } }; return translator; }

实现逻辑非常清晰：

• 无components时（普通文本），直接调用 i18next 的t(key)返回翻译字符串；
• 带components时（富文本），使用next-i18next的<Trans>组件，以opts.components作为插值组件映射渲染。<Trans>内部会把翻译文本中的<1>、<2>占位符替换为对应索引的 React 元素，从而让链接、强调等内嵌样式在翻译后的语言中同样生效。

这种「函数返回ReactNode」的设计，正是 Plasmic 能够与任意 i18n 框架（lingui、next-i18next 等）对接的通用接口点。

五、应用层接入：appWithTranslation与页面翻译注入

1. 用appWithTranslation包装 App

pages/_app.tsx 将整个应用交给 next-i18next 托管：

import "@/styles/globals.css"; import { appWithTranslation } from "next-i18next"; import type { AppProps } from "next/app"; function App({ Component, pageProps }: AppProps) { // const router = useRouter(); // const locale = router.locale ?? router.defaultLocale ?? "en"; // i18n.changeLanguage(locale); return <Component {...pageProps} />; } export default appWithTranslation(App);

appWithTranslation(App)会在应用根部初始化 i18next 实例。被注释掉的代码提示了可选的增强点：在 App 内读取router.locale并调用i18n.changeLanguage(locale)，可在语言切换时主动同步 i18next 的语言状态。

2. 在getStaticProps中加载服务端翻译

pages/index.tsx 展示了「Plasmic 数据预取 + 翻译预取」的完整静态生成流程：

export const getStaticProps: GetStaticProps = async (context) => { const plasmicData = await PLASMIC.fetchComponentData("/"); const pageMeta = plasmicData.entryCompMetas[0]; const queryCache = await extractPlasmicQueryData( <PlasmicRootProvider loader={PLASMIC} prefetchedData={plasmicData} pageParams={pageMeta.params} > <PlasmicComponent component={pageMeta.displayName} /> </PlasmicRootProvider> ); const trans = await serverSideTranslations(context.locale ?? "en"); return { props: { plasmicData, queryCache, ...trans }, revalidate: 300, }; };

关键点：

• serverSideTranslations(context.locale ?? "en")是 next-i18next 的服务端工具，按当前 locale 加载public/locales/<locale>/common.json，并把_nextI18Next等初始化数据并入 props；
• revalidate: 300启用 ISR（增量静态再生），页面每 300 秒失效重建，无需部署 webhook 即可更新 Plasmic 内容。

3. 注入 translator 并渲染 Plasmic 组件

页面组件将 translator 传入PlasmicRootProvider：

export default function HomePage(props: { plasmicData?: ComponentRenderData; queryCache?: Record<string, any>; }) { const { plasmicData, queryCache } = props; const router = useRouter(); const translator = usePlasmicTranslator(); if (!plasmicData || plasmicData.entryCompMetas.length === 0) { return <Error statusCode={404} />; } const pageMeta = plasmicData.entryCompMetas[0]; return ( <PlasmicRootProvider loader={PLASMIC} prefetchedData={plasmicData} prefetchedQueryData={queryCache} pageParams={pageMeta.params} pageQuery={router.query} translator={translator} > <PlasmicComponent component={pageMeta.displayName} componentProps={{ englishButton: { locale: "en", color: router.locale === "en" ? "blue" : "blueBorder", }, spanishButton: { locale: "es", color: router.locale === "es" ? "blue" : "blueBorder", }, }} /> </PlasmicRootProvider> ); }

这段代码体现了两层含义：

• 翻译层：translator一旦注入，Plasmic 组件内部所有绑定本地化 key 的文本都会走usePlasmicTranslator返回的翻译函数，实现文案的多语言渲染；
• 交互层：通过componentProps把englishButton、spanishButton两个按钮组件与 locale 绑定——当前语言为en时英文按钮使用实心blue样式，否则使用描边blueBorder，es同理。用户在 Plasmic Studio 中编辑这两个按钮的 props 结构时，会自动获得语言切换能力，无需改动 React 代码。

六、运行与验证

在examples/nextjs-i18n-i18next目录下执行：

# 1. 安装依赖（仓库使用 npm，已提供 package-lock.json） npm install # 2. 从 Plasmic Studio 项目导出英文文案 npm run plasmic-i18n # 3. 启动开发服务器 npm run dev

然后访问：

• http://localhost:3000/en：英文页面；
• http://localhost:3000/es：西班牙语页面（富文本中的链接与强调样式会由<Trans>正确还原）。

如需修改文案，在 Plasmic Studio 中编辑文本后重新运行npm run plasmic-i18n刷新public/locales/en/common.json，再更新对应语言的翻译文件即可，ISR 会在 300 秒后自动让线上页面生效。

七、小结：Plasmic i18n 的接入范式

从本示例可以提炼出 Plasmic 接入第三方 i18n 框架的通用三步范式：

1. 导出：用 CLIplasmic localization-strings（packages/cli/src 中的lib.ts与index.ts实现了该命令）将 Studio 项目文案落盘为 JSON；
2. 翻译：按public/locales/<locale>/common.json约定为各语言补充翻译，保留富文本占位符；
3. 注入：实现符合 PlasmicTranslator 签名的翻译函数，通过PlasmicRootProvider的translatorprop 传入，再配合appWithTranslation与服务端serverSideTranslations完成整链路。

nextjs-i18n-i18next示例采用next-i18next，而仓库中的 nextjs-i18n-intl 与 nextjs-i18n-lingui 分别演示了 Intl 与 lingui 的同类方案——三者共享同一套translator注入机制，差异仅在于翻译器内部调用的 i18n 框架 API。理解这一抽象，即可在任意 Next.js 国际化方案中复用 Plasmic 的可视化内容。

• 低代码
• 前端
• 后端