前端国际化实战：从需求到落地的完整实践

news2024/12/14 7:22:21

"我们要开拓东南亚市场了！"产品经理小王兴奋地告诉我这个消息。作为技术负责人,我立刻意识到这意味着我们需要对整个系统进行国际化改造。说实话,虽然之前也做过一些多语言的项目,但面对一个正在运行的大型系统,国际化改造的挑战还是不小。

回想起上周的需求评审会,我们讨论了很多细节问题：不同语言的排版布局、日期时间格式、货币单位转换等等。经过一番头脑风暴,我们制定了一个详细的改造计划。今天就来分享这个过程中的实战经验。

需求分析

首先,我们需要明确国际化的具体需求。通过和产品、运营的深入沟通,我们确定了几个关键点：

第一个挑战是语言切换。系统要支持英语、泰语、越南语和印尼语,而且要能够根据用户的浏览器设置自动选择默认语言。"用户第一次访问时,要让他感觉这就是为他准备的。"产品经理特别强调这一点。

第二个挑战是内容适配。不同语言的文字长度差异很大,比如英文的"Submit"翻译成泰语后会长很多。而且有些语言还有特殊的书写方向和字体要求。

第三个挑战是本地化处理。日期、时间、货币这些格式在不同地区都有各自的规范。"不能让用户看到 2024/12/3,他们习惯的可能是 3/12/2024。"运营同学提醒道。

技术方案

经过调研,我们设计了一个灵活的国际化方案。就像搭建一个多语言的图书馆,我们需要有清晰的分类系统(语言配置),便捷的检索方式(语言切换),以及统一的管理制度(翻译流程)。

首先是语言包的组织方式：

// 按功能模块划分语言包
const messages = {
  en: {
    common: {
      submit: 'Submit',
      cancel: 'Cancel',
      confirm: 'Confirm'
    },
    auth: {
      login: 'Log In',
      register: 'Sign Up',
      forgotPassword: 'Forgot Password?'
    },
    dashboard: {
      welcome: 'Welcome back, {name}',
      totalUsers: '{count} users',
      activeToday: '{count} active today'
    }
  },
  th: {
    common: {
      submit: 'ส่ง',
      cancel: 'ยกเลิก',
      confirm: 'ยืนยัน'
    }
    // ... 其他泰语翻译
  }
}

然后是语言切换的核心逻辑：

// hooks/useI18n.ts
function useI18n() {
  const [locale, setLocale] = useState(() => {
    // 优先使用用户设置的语言
    const savedLocale = localStorage.getItem('locale')
    if (savedLocale) return savedLocale

    // 其次使用浏览器语言
    const browserLocale = navigator.language.split('-')[0]
    return supportedLocales.includes(browserLocale) ? browserLocale : 'en'
  })

  const formatMessage = useCallback(
    (key: string, values?: Record<string, any>) => {
      const template = get(messages[locale], key, key)
      if (!values) return template

      return template.replace(/\{(\w+)\}/g, (_, key) => values[key] || '')
    },
    [locale]
  )

  const changeLocale = useCallback((newLocale: string) => {
    if (!supportedLocales.includes(newLocale)) return
    setLocale(newLocale)
    localStorage.setItem('locale', newLocale)
    // 更新 HTML 的 lang 属性
    document.documentElement.lang = newLocale
    // 更新 moment 的语言设置
    moment.locale(newLocale)
  }, [])

  return { locale, formatMessage, changeLocale }
}

对于日期和货币的处理,我们使用了专门的库：

// utils/formatter.ts
import { format } from 'date-fns'
import * as locales from 'date-fns/locale'

export function formatDate(date: Date, locale: string) {
  const dateLocale = locales[locale] || locales.enUS
  return format(date, 'PPP', { locale: dateLocale })
}

export function formatCurrency(amount: number, locale: string) {
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency: getCurrencyByLocale(locale)
  }).format(amount)
}

// 根据语言获取对应的货币
function getCurrencyByLocale(locale: string) {
  const currencyMap = {
    en: 'USD',
    th: 'THB',
    vi: 'VND',
    id: 'IDR'
  }
  return currencyMap[locale] || 'USD'
}

实践细节

在实际开发中,我们遇到了一些有趣的挑战。比如泰语的字体渲染问题,我们通过动态加载字体来解决：

// 动态加载字体
const loadFont = async (locale: string) => {
  const fontMap = {
    th: 'https://fonts.googleapis.com/css2?family=Noto+Sans+Thai&display=swap',
    vi: 'https://fonts.googleapis.com/css2?family=Noto+Sans+Vietnamese&display=swap'
  }

  if (!fontMap[locale]) return

  const link = document.createElement('link')
  link.rel = 'stylesheet'
  link.href = fontMap[locale]
  document.head.appendChild(link)
}

为了提高翻译的效率,我们开发了一个翻译管理平台,支持在线编辑和自动同步：

// 翻译同步服务
async function syncTranslations() {
  // 获取所有需要翻译的文本
  const texts = await extractTextsFromCode()

  // 对比已有翻译,找出缺失的部分
  const missingTranslations = findMissingTranslations(texts)

  // 使用翻译服务进行翻译
  const translations = await translateTexts(missingTranslations)

  // 更新语言包
  await updateLanguageFiles(translations)
}