@cvo/plugin-i18n-fluent

Internationalization plugin for CVO Framework based on Mozilla's Project Fluent. It provides high-performance, flexible, and naturally phrased translations for complex linguistic requirements.

🚀 Features

• Asymmetric Translation: Handles complex plurals, gender, and language-specific adjustments with ease.
• Type Safety: Integration with CVO's compiler allows for type-checking translation keys in the frontend.
• High Performance: Powered by @fluent/bundle for blazing-fast parsing and formatting.
• BCP 47 Compliant: Strictly follows standard language tags (e.g., zh-Hans, en-US) for global consistency.

🛠 Configuration

Configure i18n in your cvo.config.ts:

import { defineConfig } from '@cvo/core';
import { FluentI18nProvider } from '@cvo/plugin-i18n-fluent';

export default defineConfig({
  i18n: {
    provider: new FluentI18nProvider(),
    defaultLocale: 'zh-Hans',
    locales: ['en-US', 'zh-Hans'],
    fallbackLocale: 'en-US',
  },
});

🧠 Usage

Backend API

The framework automatically detects the locale from Accept-Language headers, query parameters (?lang=), or cookies. You can use either the useI18n hook or the @I18n() parameter decorator.

Using Hook (Recommended)

import { useI18n } from '@cvo/server';

export async function getWelcomeMessage(name: string) {
  const { t } = useI18n();
  return t('todo-welcome', { name });
}

Using Decorator (Controller Method)

import { http, I18n } from '@cvo/core';

export class TodoController {
  @http('GET', '/welcome')
  async welcome(@I18n() t: (key: string, args?: any) => string) {
    return { message: t('todo-welcome', { name: 'John' }) };
  }
}

Frontend (Vue)

CVO generates typed helpers for your translations. Use the $t global property or the useI18n hook in your components.

<template>
  <div>
    <h1>{{ $t('todo-welcome', { name: 'John' }) }}</h1>
    <p>{{ $t('todo-count', { count: 5 }) }}</p>
  </div>
</template>

📁 Directory Structure & BCP 47

CVO strictly follows BCP 47 language tags. Place your .ftl files in the locales directory using standard codes (e.g., zh-Hans for Simplified Chinese, en-US for American English).

my-app/
  locales/
    en-US/
      common.ftl
      todo.ftl
    zh-Hans/
      common.ftl
      todo.ftl

Sample FTL File (locales/zh-Hans/todo.ftl)

todo-welcome = 欢迎使用待办事项应用，{ $name }！
todo-count = { $count ->
    [one] 你有 1 个待办事项
   *[other] 你有 { $count } 个待办事项
}