从零开始学多语言预渲染：video-splitter 项目技术解析

欢迎来到 utities.online 技术教程系列

你好，开发者朋友！欢迎阅读我们的技术教程系列。今天，我们将深入剖析 utities.online 工具合集网站自研的视频分割工具 —— video-splitter 的多语言预渲染实现机制。这不仅是一个技术解析，更是一份实用的学习指南，将帮助你掌握如何为现代 Web 应用实现高效的多语言支持。

作为 utities.online 平台的核心工具之一，video-splitter 让用户能够轻松地将视频文件分割成自定义长度的片段，支持拖放操作，无需安装任何软件，所有处理均在浏览器内完成。而为了更好地服务全球用户，我们实现了一套完整的多语言预渲染方案。

什么是多语言预渲染？

多语言预渲染是一种在构建时为每种语言生成静态 HTML 文件的技术。它结合了服务端渲染（SSR）和静态站点生成（SSG）的优势：

• 提升用户体验：用户可以立即看到内容，无需等待客户端渲染完成
• 改善搜索引擎优化：搜索引擎可以直接抓取完整的内容，而不是等待 JavaScript 执行
• 降低服务器负载：预生成的静态文件可以直接提供给用户，减少了服务器实时渲染的压力
• 支持国际化：为不同语言的用户提供定制化的内容和体验

这种技术特别适合需要支持多语言且注重性能和 SEO 的 Web 应用，如 video-splitter 这样的工具型网站。

技术栈解析

在实现 video-splitter 的多语言预渲染功能时，我们选择了以下技术栈：

项目结构概览

在开始学习具体实现前，让我们先了解一下 video-splitter 项目的核心文件结构：

├── src/
│   ├── i18n/
│   │   ├── index.ts           # 国际化配置入口文件，定义语言列表和初始化函数
│   │   └── locales/           # 翻译文件目录，包含所有支持的语言
│   │       ├── en/            # 英语翻译文件
│   │       ├── zh/            # 中文翻译文件
│   │       └── [其他语言]/    # 其他支持语言的翻译文件
│   ├── entry-server.tsx       # 服务器端渲染入口，包含关键的 render 函数
│   └── constants.ts           # 常量定义，如 DOMAIN_NAME 和 SITE_ID
├── prerender.js               # 预渲染脚本，负责为每种语言生成静态 HTML
└── package.json               # 项目配置和脚本，定义构建和预渲染命令

这个结构体现了关注点分离的设计原则：国际化相关的代码集中在 i18n 目录，渲染逻辑分离到客户端和服务器端，预渲染过程独立于主应用逻辑。

多语言预渲染工作流程详解

步骤 1：预渲染脚本初始化

prerender.js 是整个预渲染过程的起点，它的主要作用是设置环境并准备生成多语言静态页面：

javascript
// 导入必要的 Node.js 模块
import fs from 'node:fs'
import path from 'node:path'
import url from 'node:url'
// 设置基本常量
const isProduction = process.env.NODE_ENV === 'production'
const port = process.env.PORT || 5173
const base = process.env.BASE || '/'
// 获取当前文件所在目录的绝对路径
const __dirname = path.dirname(url.fileURLToPath(import.meta.url))
// 工具函数：将相对路径转换为绝对路径
const toAbsolute = (p) => path.resolve(__dirname, p)
// 读取构建后的 HTML 模板文件
const templateHtml = fs.readFileSync('./dist/static/index.html', 'utf-8')

步骤 2：动态检测支持的语言

为了实现灵活的国际化支持，video-splitter 项目不硬编码支持的语言列表，而是通过扫描文件系统动态检测所有可用的语言：

javascript
// 动态获取所有支持的语言
const localesDir = path.resolve(__dirname, 'src/i18n/locales')
const languages = fs.readdirSync(localesDir).filter(name => {
    const fullPath = path.join(localesDir, name)
    return fs.statSync(fullPath).isDirectory()
})

步骤 3：生成多语言路由

基于检测到的语言列表，我们需要为每种语言生成对应的路由。在这个项目中，我们采用了一个常见的国际化路由策略：英语作为默认语言，使用根路径 /，其他语言则使用语言代码作为前缀，如 /zh/ 表示中文：

javascript
// 为每种语言生成路由
const routes = ['/'].concat(languages.filter(lang => lang !== 'en').map(lang => `/${lang}`))

步骤 4：服务器端渲染实现

服务器端渲染是多语言预渲染的核心环节。在 src/entry-server.tsx 文件中，项目实现了一个强大的 render 函数，它负责将 React 组件转换为包含多语言内容的 HTML 字符串：

javascript
export async function render(url: string, languages: string[]) {
  // 步骤1：根据URL获取对应语言的SEO内容
  const seoContent = await getSeoContent(url)
  
  // 步骤2：初始化i18n实例并设置当前语言
  const i18nInstance = await initI18n(seoContent.language)
  i18nInstance.changeLanguage(seoContent.language)
  
  // 步骤3：使用ReactDOMServer的renderToString方法渲染应用
  const html = renderToString(
    <StrictMode>
      <App />
    </StrictMode>,
  )
  // 步骤4：生成hreflang标签和其他头部内容
  // ...
}

步骤5：多语言内容替换与文件生成

现在，让我们看看预渲染脚本如何为每种语言生成最终的静态 HTML 文件：

javascript
for (const route of routes) {
    // 确定当前路由的语言
    const lang = route === '/' ? 'en' : route.split('/')[1]
    const rendered = await render(route, languages)
    const html = template
        .replace(`<!--app-head-->`, rendered.head ?? '')
        .replace(`<!--app-html-->`, rendered.html ?? '')
        .replace(/<html([^>]*)>/, (match, attrs) => {
            // 设置 lang 属性
            if (attrs && /\blang\s*=/.test(attrs)) {
                return `<html${attrs.replace(/\blang\s*=\s*(["'])[^"']*\1/, `lang="${lang}"`)}>`
            } else {
                return `<html${attrs ? ` ${attrs}` : ''} lang="${lang}">`
            }
        })
    // 保存生成的 HTML 文件
    const filePath = `dist/static${route}/index.html`
    const dir = path.dirname(toAbsolute(filePath))
    if (!fs.existsSync(dir)) {
        fs.mkdirSync(dir, { recursive: true })
    }
    fs.writeFileSync(toAbsolute(filePath), html)
    console.log(`Prerendered ${filePath} with lang="${lang}"`)
}

国际化配置详解

在 video-splitter 项目中，国际化功能是整个多语言预渲染的基础。这些功能主要通过 src/i18n/index.ts 文件实现：

javascript
// 支持的语言列表
// 项目支持28种语言，覆盖全球主要语言区域
export const languages = [
    'en', 'zh', 'ar', 'bn', 'cs', 'da', 'de', 'es', 'fi', 'fr',
    'hi', 'hu', 'id', 'it', 'ja', 'ko', 'nl', 'no', 'pl', 'pt',
    'ru', 'sv', 'th', 'tl', 'tr', 'tw', 'ur', 'vi'
];
// 动态导入语言翻译文件的函数
export const importTranslations = async (language: string) => {
    try {
        // 动态导入指定语言的翻译文件
        const translationsModule = await import(`./locales/${language}/translation.json`);
        return translationsModule.default;
    } catch (error) {
        // 优雅的错误处理：当请求的语言文件不存在时，自动回退到英文
        const defaultTranslationsModule = await import('./locales/en/translation.json');
        return defaultTranslationsModule.default;
    }
};
// 初始化国际化系统的函数
export const initI18n = async (language?: string) => {
    try {
        // 预加载常用语言翻译，提升用户体验
        const translations = await preloadCommonTranslations();
        
        // 调用共享的初始化函数，完成i18n配置
       return await sharedInitI18n(translations, language);
    } catch (error) {
        // 健壮的错误处理：当出现任何初始化问题时，降级到基本配置
       return await sharedInitI18n({});
    }
};

构建与执行流程详解

video-splitter 项目在 package.json 中定义了清晰的构建和预渲染命令：

javascript
"scripts": {
  // ...
  "build:server": "vite build --config vite.config.server.ts",
  "generate": "pnpm run build && pnpm run build:server && node prerender"
}

执行 pnpm run generate 命令会触发以下三个关键步骤：

1. 构建客户端代码 (build)

   • 使用 Vite 构建优化后的客户端 JavaScript、CSS 和 HTML 文件
   • 生成适用于浏览器环境的代码，包含所有必要的 polyfill
   • 对静态资源进行优化，如压缩、哈希命名等

2. 构建服务器端渲染代码 (build:server)

   • 使用特定的服务器端配置构建代码
   • 生成可在 Node.js 环境中运行的服务器端渲染代码
   • 排除浏览器特定的 API 和依赖

3. 运行预渲染脚本 (node prerender)

   • 调用前面构建的服务器端渲染代码
   • 为每种支持的语言生成静态 HTML 文件
   • 将生成的文件保存到正确的目录结构中

翻译文件结构详解

在 video-splitter 项目中，翻译文件采用了结构化的 JSON 格式，这种设计使国际化内容管理变得直观且易于维护：

json
{
  "videoSplitter": {
    "title": "VideoSplitter - Fast Video Splitting Tool",
    "description": "Split your videos into custom-length clips or divide them equally with ease...",
    "uploadVideo": "Upload Video",
    "dragAndDrop": "Drag and drop your video file here",
    // 更多翻译...
  },
  "common": {
    "processing": "Processing",
    "success": "Success",
    "error": "Error"
  }
}

翻译文件采用了两级命名空间的组织策略：

1. 功能模块命名空间 (videoSplitter)

   • 包含特定于视频分割器功能的翻译文本
   • 涵盖界面元素、操作提示和功能描述

2. 通用模块命名空间 (common)

   • 存储在多个功能模块间共享的通用文本
   • 包括状态提示、操作反馈和通用按钮文本

关键技术亮点解析

video-splitter 项目的多语言预渲染实现包含多项精心设计的技术亮点：

1. 动态语言检测机制

项目采用了现代化的动态语言检测方案，而不是硬编码支持的语言列表：

• 通过扫描 src/i18n/locales/ 目录自动发现所有可用语言
• 新添加语言时无需修改核心代码，只需创建对应的语言目录和翻译文件

2. 自动化多语言路由生成

预渲染脚本实现了完全自动化的多语言路由结构生成：

• 根据检测到的语言列表，自动创建对应的目录结构
• 为每种语言版本生成独立的 HTML 文件

3. 全方位国际化 SEO 优化

项目实现了完整的国际化 SEO 支持策略：

• 为每种语言版本设置符合 W3C 标准的 lang 属性，明确内容语言
• 自动生成 hreflang 标签，帮助搜索引擎识别同一内容的不同语言版本
• 为每种语言版本配置独立的元数据（标题、描述、关键词）

4. 健壮的语言降级机制

项目设计了优雅的语言降级处理策略：

• 当请求的语言翻译文件不存在或加载失败时，系统会自动回退到英文版本
• 降级过程对用户完全透明，不会出现内容缺失或错误提示

5. 高性能翻译预加载策略

为了提升运行时性能，项目实现了先进的翻译预渲染机制：

javascript
export const preloadCommonTranslations = async () => {
    try {
        // 并行加载所有语言的翻译文件
        const translationPromises = languages.map(async (lang) => {
            const translations = await importTranslations(lang);
            return { [lang + 'Translations']: translations };
        });
        // 等待所有翻译文件加载完成
        const results = await Promise.all(translationPromises);
        
        // 创建一个统一的翻译映射对象
        const translationsMap: Record<string, any> = {};
        // 将所有加载的翻译合并到一个对象中
        results.forEach(result => {
            Object.assign(translationsMap, result);
        });
        // 返回合并后的翻译映射
        return translationsMap;
    } catch (error) {
        // 错误处理：记录加载失败信息，但不中断程序执行
        console.error('Failed to preload common translations', error);
        // 返回空对象，确保即使预加载失败，应用程序也能正常运行
        return {};
    }
};

性能优化考量详解

在 video-splitter 项目的多语言预渲染实现中，性能优化是一个关键考量点：

1. 构建时预渲染优化

项目采用了构建时预渲染而非运行时渲染的策略，带来了显著的性能提升：

• 单次渲染，多处使用：预渲染过程只在构建时执行一次，生成的静态 HTML 文件可以直接提供给所有用户
• 减轻服务器负担：无需在每个用户请求时动态渲染页面，大大降低了服务器的计算负载
• 提升客户端体验：用户直接获取完整的 HTML 内容，减少了客户端的 JavaScript 执行和渲染时间

2. 多语言路由的资源路径管理

项目通过智能设置 <base> 标签，优雅地解决了多语言路由下的资源加载问题：

javascript
// 计算base URL - 对于所有路由，使用根路径作为base URL
// 这确保了无论在哪个语言子目录下，资源都能正确加载
const baseUrl = '/'
// 在HTML头部添加base标签，指定所有相对URL的基础路径
const head = renderToString(
    <>
      <base href={baseUrl} />
      {/* 其他头部内容 */}
    </>
)

3. 高效构建缓存策略

项目选择 Vite 作为构建工具，充分利用了其先进的缓存机制，显著提高了构建和预渲染的速度：

• 模块级缓存：Vite 对每个模块进行独立缓存，只重新构建发生变化的模块
• 热模块替换：在开发过程中，只更新修改的部分，无需重新构建整个应用
• 预构建外部依赖：将第三方依赖预先构建成优化的 ESM 模块，提高后续构建速度

总结

video-splitter 项目的多语言预渲染机制通过结合 Node.js、React 服务器端渲染和文件系统操作，实现了高效的多语言静态页面生成。这种方案不仅提升了用户体验和搜索引擎可见性，还保持了代码的可扩展性和可维护性。

想了解更多技术干货，请访问我们的 。也欢迎体验我们的在线工具集 ，包括视频分割器、图片对比专家等多种实用工具。