Max ebf3dcc870 Refactor Documentation for Backend API Method Naming and Iframe Communication

- Updated iframe documentation to remove token handling from the setup message, clarifying the focus on theme and locale.
- Added a new section in MCP documentation detailing HTTP transport configuration for API access, enhancing clarity on authorization.
- Revised frontend API documentation to standardize method naming by removing the 'Api' prefix in examples, improving consistency across backend calls.
- Enhanced event handling documentation by updating method names in examples, ensuring alignment with the new naming conventions.

2026-01-03 11:42:23 +08:00

5.2 KiB

Raw Blame History

Internationalization (i18n)

SUI provides built-in support for internationalization with translation markers and locale files.

Translation Markers

Static Text

Use s:trans attribute for static text:

<span s:trans>Hello World</span>
<button s:trans>Submit</button>
<p s:trans>Welcome to our application</p>

In Expressions

Use '::' prefix in expressions:

<span>{{ '::Welcome' }}</span>
<span>{{ '::Hello, ' + name }}</span>
<p>{{ '::You have ' + count + ' messages' }}</p>

In Scripts

Use __m() function:

<script>
  const message = __m("Welcome back");
  const greeting = __m("Hello, ") + userName;
  alert(__m("Are you sure?"));
</script>

Locale Files

Directory Structure

/templates/<template>/
└── __locales/
    ├── en-us/
    │   ├── home.yml
    │   └── users/list.yml
    └── zh-cn/
        ├── home.yml
        └── users/list.yml

File Format

__locales/zh-cn/home.yml:

name: zh-cn
direction: ltr
timezone: +08:00
formatter: scripts.locale

messages:
  Hello World: 你好世界
  Welcome: 欢迎
  "Hello, ": "你好，"
  Submit: 提交
  "You have %d messages": "你有 %d 条消息"

keys:
  page_title: 首页
  nav_home: 首页
  nav_about: 关于

script_messages:
  Welcome back: 欢迎回来
  "Are you sure?": "你确定吗？"

Sections

Section	Description
`name`	Locale identifier
`direction`	Text direction (`ltr` or `rtl`)
`timezone`	Timezone offset
`formatter`	Custom formatter process
`messages`	Translations for `s:trans` and `::`
`keys`	Named translation keys
`script_messages`	Translations for `__m()`

Using Translations

HTML Templates

<!-- Static translation -->
<h1 s:trans>Welcome to our site</h1>

<!-- Dynamic translation -->
<p>{{ '::Hello, ' + user.name }}</p>

<!-- With variables -->
<span>{{ '::You have ' + count + ' items' }}</span>

Named Keys

Named keys are used internally for translation lookup. The keys section in locale files provides named references for translations that can be used programmatically.

Scripts

import { Component } from "@yao/sui";

const self = this as Component;

self.ShowMessage = () => {
  const message = __m("Operation completed");
  alert(message);
};

self.Confirm = () => {
  return confirm(__m("Are you sure you want to delete?"));
};

Locale Detection

SUI detects locale from:

Cookie (locale or umi_locale)
Browser language
Default (en-us)

Access Current Locale

<html lang="{{ $locale }}">
  <body dir="{{ $direction }}">
    ...
  </body>
</html>

Custom Formatter

Define a custom formatter process:

# In locale file
formatter: scripts.locale.format

scripts/locale.js:

function format(text, args) {
  // Custom formatting logic
  return text.replace(/%d/g, () => args.shift());
}

RTL Support

For right-to-left languages:

# __locales/ar/home.yml
name: ar
direction: rtl
timezone: +03:00

messages:
  Hello: مرحبا

<body dir="{{ $direction }}">
  <!-- Content automatically flows RTL -->
</body>

Building Translations

Generate Translation Files

yao sui trans <sui> <template>

This command:

Scans all pages for translation markers
Generates/updates locale files
Builds the template

Translation Workflow

Add s:trans or :: markers to your HTML
Run yao sui trans to extract strings
Edit locale files to add translations
Build with yao sui build

Complete Example

/home/home.html:

<div class="home">
  <h1 s:trans>Welcome to our application</h1>

  <p>{{ '::Hello, ' + user.name }}</p>

  <div class="stats">
    <span>{{ '::You have ' + messageCount + ' messages' }}</span>
  </div>

  <nav>
    <a href="/" s:trans>Home</a>
    <a href="/about" s:trans>About</a>
    <a href="/contact" s:trans>Contact</a>
  </nav>

  <button s:on-click="ShowWelcome" s:trans>Show Welcome</button>
</div>

<script>
  import { Component } from "@yao/sui";

  const self = this as Component;

  self.ShowWelcome = () => {
    alert(__m("Welcome to our site!"));
  };
</script>