Max bdfe7e83e8 Revise Agent and SUI Documentation for Clarity and Consistency

- Updated the Agent API documentation to reflect a new structure, emphasizing quick start instructions and reorganizing content for better readability.
- Renamed the main documentation title to "Yao Agent" and streamlined sections, including API endpoints and file management.
- Adjusted the SUI documentation to align with the Yao App Engine license, ensuring consistency across project documentation.

2026-01-01 11:08:30 +08:00

3.7 KiB

Raw Blame History

Internationalization (i18n)

Locale Files

Create locales/ directory in the assistant:

assistants/my-assistant/
└── locales/
    ├── en-us.yml
    ├── zh-cn.yml
    └── ja.yml

Locale File Format

# locales/en-us.yml
name: My Assistant
description: A helpful AI assistant

chat:
  title: New Chat
  description: How can I help you today?
  prompts:
    - What can you do?
    - Help me with a task
    - Tell me about yourself

messages:
  welcome: Welcome back!
  error: Something went wrong
  processing: Processing your request...

# locales/zh-cn.yml
name: 我的助手
description: 一个有帮助的AI助手

chat:
  title: 新对话
  description: 今天我能帮您什么？
  prompts:
    - 你能做什么？
    - 帮我完成一个任务
    - 介绍一下你自己

messages:
  welcome: 欢迎回来！
  error: 出了点问题
  processing: 正在处理您的请求...

Using Translations

In package.yao

Use {{ key }} syntax:

{
  "name": "{{ name }}",
  "description": "{{ description }}",
  "placeholder": {
    "title": "{{ chat.title }}",
    "description": "{{ chat.description }}",
    "prompts": [
      "{{ chat.prompts.0 }}",
      "{{ chat.prompts.1 }}",
      "{{ chat.prompts.2 }}"
    ]
  }
}

In Prompts

- role: system
  content: |
    You are {{ name }}.
    {{ description }}

    Respond in the user's language.

Locale Detection

The system detects locale from:

Request header Accept-Language
User preference (stored in memory)
Default: en-us

Override in Hook

function Create(ctx: agent.Context, messages: agent.Message[]): agent.Create {
  // Get user preference
  const userLocale = ctx.memory.user.Get("preferred_locale");

  return {
    messages,
    locale: userLocale || "en-us"
  };
}

Global Translations

Define global translations in agent/locales/:

agent/
└── locales/
    ├── en-us.yml
    └── zh-cn.yml

These are available to all assistants via the __global__ namespace.

Accessing Translations in Hooks

function Create(ctx: agent.Context, messages: agent.Message[]): agent.Create {
  const locale = ctx.locale;  // e.g., "en-us"

  // Use locale for custom logic
  if (locale.startsWith("zh")) {
    return {
      messages,
      prompt_preset: "chinese"
    };
  }

  return { messages };
}

Nested Keys

Access nested values with dot notation:

# locales/en-us.yml
errors:
  validation:
    required: This field is required
    invalid: Invalid value
  network:
    timeout: Connection timed out

{
  "placeholder": {
    "title": "{{ errors.validation.required }}"
  }
}

Fallback Behavior

If a translation key is not found:

Try the requested locale
Fall back to en-us
Return the key itself if not found

Dynamic Locale Content

function Create(ctx: agent.Context, messages: agent.Message[]): agent.Create {
  // Add locale-specific system message
  const localeGreeting = {
    "en-us": "Hello! How can I help you?",
    "zh-cn": "你好！有什么可以帮您的？",
    "ja": "こんにちは！何かお手伝いできますか？"
  };

  const greeting = localeGreeting[ctx.locale] || localeGreeting["en-us"];

  return {
    messages: [
      { role: "system", content: `Greeting: ${greeting}` },
      ...messages
    ]
  };
}

Best Practices

Keep keys consistent - Use the same keys across all locale files
Use nested structure - Organize related translations together
Provide fallbacks - Always have en-us as the base locale
Test all locales - Verify translations render correctly
Use context variables - Combine with $CTX.locale in prompts

3.7 KiB Raw Blame History