Vendure电商平台：Admin UI国际化翻译指南

Vendure电商平台：Admin UI国际化翻译指南

vendure A headless GraphQL commerce platform for the modern web 项目地址: https://gitcode.com/gh_mirrors/ve/vendure

前言

在全球化电商业务中，多语言支持是必不可少的特性。Vendure作为现代化的电商平台，其Admin UI提供了完整的国际化(i18n)支持。本文将详细介绍如何为Vendure Admin UI添加自定义翻译，包括覆盖现有翻译和添加全新语言支持。

翻译基础概念

翻译文件格式

Vendure Admin UI采用Messageformat规范处理国际化字符串，这是一种强大的国际化消息格式标准，支持复杂的语法结构如复数形式、性别区分等。

每个语言对应一个JSON文件，采用扁平化的嵌套结构组织翻译键值对。例如：

{
  "section": {
    "key1": "翻译文本1",
    "key2": "翻译文本2"
  }
}

变量插值

翻译字符串可以包含变量插值，这在处理动态内容时非常有用：

{
  "order": {
    "items-count": "共{count}件商品"
  }
}

在前端模板中使用时，通过传递上下文对象实现变量替换：

<span>{{ 'order.items-count' | translate:{ count: 5 } }}</span>

添加新语言支持

准备工作

1. 确定目标语言的ISO 639-1代码（如中文为"zh"）
2. 准备基础翻译文件，建议从英文文件开始修改

实施步骤

1. 创建翻译文件

   在项目中创建<languageCode>.json文件，如zh.json。文件内容应包含完整的翻译键值对。

2. 配置Vendure

   修改Vendure配置文件，注册新语言并指定翻译文件路径：

import path from 'path';
import { VendureConfig, LanguageCode } from '@vendure/core';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
import { compileUiExtensions } from '@vendure/ui-devkit/compiler';

export const config: VendureConfig = {
  plugins: [
    AdminUiPlugin.init({
      app: compileUiExtensions({
        outputPath: path.join(__dirname, 'admin-ui'),
        extensions: [{
          translations: {
            zh: path.join(__dirname, 'translations/zh.json'),
          }
        }],
      }),
      adminUiConfig: {
        defaultLanguage: LanguageCode.zh,
        availableLanguages: [LanguageCode.zh, LanguageCode.en],
      }
    }),
  ],
};

最佳实践

1. 保持翻译文件结构一致，便于维护
2. 使用专业翻译工具确保翻译质量
3. 考虑文化差异，避免直译导致的歧义

自定义UI扩展的翻译

翻译文件组织

对于自定义UI扩展，可以采用以下两种组织方式：

1. 单一文件：所有翻译集中在一个文件中
2. 模块化文件：按功能模块拆分翻译文件，使用glob模式匹配：

translations: {
  de: path.join(__dirname, 'extensions/**/*.de.json'),
}

命名空间管理

为避免与核心翻译冲突，应为自定义扩展使用独特的命名空间：

{
  "my-plugin": {
    "action-button": "执行操作",
    "status-label": "当前状态"
  }
}

高级特性

复数处理

Messageformat支持复杂的复数形式处理：

{
  "product": {
    "inventory-level": "{count, plural, =0 {无库存} one {1件库存} other {{count}件库存}}"
  }
}

日期/数字格式化

可通过Messageformat实现本地化的日期和数字显示：

{
  "order": {
    "created-at": "创建于{date, date, medium}"
  }
}

调试与测试

1. 开发模式：使用--debug标志运行，查看缺失的翻译键
2. 生产环境：确保所有关键路径都有备用翻译
3. 测试策略：
   • 验证所有UI元素在不同语言下的显示
   • 检查长文本在界面中的布局
   • 测试RTL语言(如阿拉伯语)的特殊处理

总结

Vendure的国际化系统提供了灵活强大的多语言支持能力。通过合理组织翻译文件、遵循最佳实践，可以轻松实现Admin UI的本地化，为全球用户提供更好的管理体验。对于复杂项目，建议建立专门的翻译维护流程，确保多语言内容的质量和一致性。

通过本文介绍的方法，开发者可以快速为Vendure电商平台添加新的语言支持，或为自定义扩展提供多语言界面，满足国际化业务需求。

vendure A headless GraphQL commerce platform for the modern web 项目地址: https://gitcode.com/gh_mirrors/ve/vendure