企业官网建设流程全解析

解决多语言组件开发痛点：Storybook国际化全流程指南

在全球化产品开发中，UI组件的国际化（Internationalization，简称i18n）是前端团队的核心挑战。当团队同时维护中文、英文、韩文等多版本界面时，如何确保组件在不同语言环境下的一致性？如何高效切换语言并验证布局适应性？Storybook作为独立的UI开发环境，提供了完整的国际化解决方案，让开发者能在隔离环境中完成多语言组件的设计、测试与交付。

国际化配置基础

Storybook通过全局变量（Globals）系统实现多语言环境的统一管理。在项目配置文件中定义支持的语言列表后，可通过工具栏快速切换，实时预览组件在不同语言下的表现。

配置语言选项

首先在预览配置文件中声明支持的语言。编辑code/core/template/stories/preview.ts，添加locale全局变量定义：

export const globalTypes = { locale: { name: 'Locale', description: 'Internationalization locale', toolbar: { icon: 'globe', items: [ { value: 'en', right: '🇺🇸', title: 'English' }, { value: 'zh', right: '🇨🇳', title: '中文' }, { value: 'es', right: '🇪🇸', title: 'Español' }, { value: 'kr', right: '🇰🇷', title: '한국어' }, ], }, }, };

这段配置会在Storybook工具栏添加语言切换按钮，支持英语、中文、西班牙语和韩语的快速切换。

设置初始语言

通过initialGlobals设置默认语言，编辑code/core/template/stories/preview.ts：

export const initialGlobals = { locale: 'zh', // 默认中文 sb_theme: 'light', };

多语言组件实现

创建国际化装饰器

装饰器（Decorator）是Storybook的核心功能，可用于包装组件并注入语言环境。创建一个LocaleProvider装饰器，根据当前全局语言提供对应的翻译文本：

// locale-decorator.tsx import { Decorator } from 'storybook/internal/types'; import { LocaleProvider } from './locale'; export const withLocale: Decorator<{ locale: string }> = (Story, context) => ( <LocaleProvider lang={context.globals.locale}> <Story /> </LocaleProvider> );

编写多语言故事

以按钮组件为例，创建支持多语言的故事文件code/core/template/stories/toolbars/globals.stories.ts：

const greetingForLocale = (locale: string) => { switch (locale) { case 'es': return 'Hola!'; case 'zh': return '你好!'; case 'kr': return '안녕하세요!'; default: return 'Hello'; } }; export default { component: Button, decorators: [(storyFn, { globals }) => ( <div> <p>当前语言: {globals.locale}</p> {storyFn({ args: { label: greetingForLocale(globals.locale) } })} </div> )], }; export const Basic = {}; export const Chinese = { globals: { locale: 'zh' } }; export const Korean = { globals: { locale: 'kr' } };

高级应用技巧

语言切换测试

Storybook的E2E测试工具可自动化验证语言切换功能。参考code/e2e-tests/addon-toolbars.spec.ts中的测试用例：

test('should switch locale and update component text', async ({ page }) => { const sbPage = new SbPage(page); await sbPage.navigateToStory('core/toolbars/globals', 'basic'); // 切换到中文 await sbPage.selectToolbar('[title="Internationalization locale"]', '#list-item-zh'); await expect(sbPage.previewRoot()).toContainText('你好'); // 切换到韩语 await sbPage.selectToolbar('[title="Internationalization locale"]', '#list-item-kr'); await expect(sbPage.previewRoot()).toContainText('안녕하세요'); });

故事级别语言覆盖

在特定故事中强制使用固定语言，确保组件在该语言下的表现一致：

export const JapaneseOnly = { globals: { locale: 'ja' }, // 忽略全局设置，强制日语 parameters: { docs: { disable: true } // 可选：在文档中隐藏此故事 } };

最佳实践与常见问题

性能优化

• 语言包懒加载：大型项目可拆分语言文件，仅加载当前选中语言
• 装饰器缓存：避免在装饰器中执行 heavy 计算，可使用Memoization

常见问题解决

1. 语言切换后组件未更新

   • 检查是否正确传递globals.locale到翻译函数
   • 确认装饰器使用最新的context值

2. RTL（从右到左）布局适配

   // 添加RTL支持 export const globalTypes = { locale: { // ...现有配置 toolbar: { // ... items: [/* ... */, { value: 'ar', right: '🇸🇦', title: 'العربية' }], } }, direction: { name: 'Direction', toolbar: { items: [{ value: 'ltr' }, { value: 'rtl' }] } } };

总结与扩展

通过Storybook的国际化方案，开发者可在隔离环境中完成多语言组件的全流程开发。核心价值包括：

• 统一的语言切换界面：无需修改代码即可验证多语言表现
• 故事级别的语言控制：灵活覆盖全局设置，满足特殊场景需求
• 自动化测试集成：确保语言切换功能稳定可靠

官方文档：docs/writing-stories/globals.md
国际化API：code/core/src/types/modules/addons.ts
示例故事：code/core/template/stories/toolbars/globals.stories.ts

建议结合项目的翻译管理系统（如i18next、react-intl）进一步优化工作流，实现翻译文本的版本控制与团队协作。