Facebook FBT 项目在 Web 应用中的集成指南

Facebook FBT 项目在 Web 应用中的集成指南

fbt A JavaScript Internationalization Framework 项目地址: https://gitcode.com/gh_mirrors/fb/fbt

前言

Facebook FBT 是一个强大的国际化框架，专门用于处理 Web 应用中的多语言翻译问题。本文将详细介绍如何在 Web 项目中集成 FBT 框架，包括环境配置、构建流程和运行时初始化等关键步骤。

环境准备

安装核心依赖

要在 Web 项目中使用 FBT，首先需要安装以下核心 NPM 包：

1. fbt - FBT 运行时核心模块
2. babel-plugin-fbt - 主 Babel 转换插件
3. babel-plugin-fbt-runtime - 辅助 Babel 转换插件
4. @fbtjs/default-collection-transform - 默认收集转换器（可选）

这些依赖项应当添加到项目的 package.json 文件中。

Babel 配置注意事项

FBT 对 Babel 插件的执行顺序有严格要求，必须确保 babel-plugin-fbt 在其他插件之前处理 AST 节点。如果遇到 JSX 转换问题，可以采用 passPerPreset 配置：

babel.transformSync(source, {
  passPerPreset: true,
  presets: [
    {plugins: ['babel-plugin-fbt', 'babel-plugin-fbt-runtime']},
    {plugins: ['其他插件']}
  ]
});

构建流程

文本收集阶段

FBT 提供了几个关键脚本来处理国际化文本：

1. fbt-manifest - 扫描项目文件，生成枚举模块清单

   • 注意：枚举模块文件名必须以 $FbtEnum 结尾（如 Colors$FbtEnum.js）

2. fbt-collectFbt - 从源代码中提取文本并输出为 JSON 格式

   • 可以使用 @fbtjs/default-collection-transform 作为默认转换器

翻译阶段

fbt-translate 脚本负责：

• 接收从收集阶段提取的文本
• 结合提供的翻译 JSON 文件
• 生成运行时所需的翻译负载

运行时配置

初始化

在使用 FBT 前必须进行初始化，示例代码如下：

import {init} from 'fbt';

init({
  translations: require('./translatedFbts.json'),
  hooks: {
    getViewerContext: () => ({
      locale: 'en_US'
    })
  }
});

动态切换语言

要实现运行时语言切换，需要完成以下步骤：

1. 注册新语言的翻译数据：

   FbtTranslations.registerTranslations(newTranslationPayload);
   

2. 更新 UI 区域设置：

   • 确保 getViewerContext() 钩子返回新的区域设置
   • 这是必要的，因为 FBT 会根据区域设置应用不同的数字变体和语音规则

最佳实践

1. 模块化翻译文件：建议按语言拆分翻译负载，便于按需加载
2. 错误处理：实现完善的错误处理机制，应对翻译缺失情况
3. 性能优化：考虑延迟加载非当前语言的翻译资源
4. 开发环境：设置开发环境下的快速反馈机制，便于发现翻译问题

总结

通过本文的介绍，您应该已经掌握了在 Web 项目中集成 Facebook FBT 框架的关键步骤。从环境配置到构建流程，再到运行时管理，FBT 提供了一套完整的解决方案来处理应用的国际化需求。合理使用这些功能，可以大大简化多语言 Web 应用的开发工作。

fbt A JavaScript Internationalization Framework 项目地址: https://gitcode.com/gh_mirrors/fb/fbt