多语言词条：后台维护，前台使用

同一套词条API支持真实SSR和CSR，缓存与回退由契约明确。

维护词条

在后台「多语言词条」选择portal命名空间，创建blog.searchPlaceholder并填写中英译文。GET /api/i18n/portal?locale=en-US返回{code:200,data:{namespace,locale,messages}}，key相对于namespace，不重复加portal前缀。

TypeScript

import type { Shell } from '@mosaic-base/shell';
import type { ArticleSDK, SiteSDK, I18nSDK } from '@mosaic-base/client-sdk';
import type { AuthClient, ServerAuthClient } from '@mosaic-base/auth-sdk';
// Declare once in your application's type contract, never import SDK implementations.
declare module '@mosaic-base/shell/contracts' {
  interface SdkRegistry {
    'site.config': Pick<SiteSDK, 'getConfig'>;
    'content.articles': Pick<ArticleSDK, 'list' | 'getBySlug' | 'getPreview' | 'search'>;
    'i18n.messages': Pick<I18nSDK, 'load' | 't' | 'clearCache' | 'refresh'>;
    'auth.client': AuthClient | ServerAuthClient;
  }
}

export async function readSearchHint(shell: Shell, locale: string) {
  const reader = await shell.getSdk('i18n.messages');
  const messages = await reader.load('portal', locale);
  return messages['blog.searchPlaceholder'] || 'Search articles…';
}
export async function refreshTranslations(shell: Shell, locale: string) {
  return (await shell.getSdk('i18n.messages')).refresh('portal', locale);
}
export async function invalidateTranslations(shell: Shell) {
  (await shell.getSdk('i18n.messages')).clearCache();
}
// Browser defaults: cacheTtlMs=60_000. Explicit server factory options use TTL0.

服务端渲染（SSR）

以下值由服务器读取，原始HTML即包含当前词条；服务端读取器TTL为0。

搜索文章…

打开博客查看效果

客户端渲染（CSR）

以下组件独立发起匿名请求，使用默认60秒SDK缓存；可以切换语言、显式刷新所选语言或失败后重试。

zh-CN · 正在读取公开词条…

加载中…

缓存、回退与导入

目标译文为空时回退zh-CN源文；源文也为空则省略键。namespace不存在返回404，请求故障不缓存为成功空数据，应用可用内置文案兜底。

SDK缓存按namespace/locale隔离，支持cacheTtlMs、clearCache及只刷新当前词条域的refresh(namespace, locale)。后台保存不会向所有已打开应用推送更新。导出JSON可回导，merge填空，replace覆盖同名键而保留未列出的键。AI翻译等待后续Agent能力。

维护词条

TypeScript

import type { Shell } from '@mosaic-base/shell';
import type { ArticleSDK, SiteSDK, I18nSDK } from '@mosaic-base/client-sdk';
import type { AuthClient, ServerAuthClient } from '@mosaic-base/auth-sdk';
// Declare once in your application's type contract, never import SDK implementations.
declare module '@mosaic-base/shell/contracts' {
  interface SdkRegistry {
    'site.config': Pick<SiteSDK, 'getConfig'>;
    'content.articles': Pick<ArticleSDK, 'list' | 'getBySlug' | 'getPreview' | 'search'>;
    'i18n.messages': Pick<I18nSDK, 'load' | 't' | 'clearCache' | 'refresh'>;
    'auth.client': AuthClient | ServerAuthClient;
  }
}

export async function readSearchHint(shell: Shell, locale: string) {
  const reader = await shell.getSdk('i18n.messages');
  const messages = await reader.load('portal', locale);
  return messages['blog.searchPlaceholder'] || 'Search articles…';
}
export async function refreshTranslations(shell: Shell, locale: string) {
  return (await shell.getSdk('i18n.messages')).refresh('portal', locale);
}
export async function invalidateTranslations(shell: Shell) {
  (await shell.getSdk('i18n.messages')).clearCache();
}
// Browser defaults: cacheTtlMs=60_000. Explicit server factory options use TTL0.

缓存、回退与导入

目标译文为空时回退zh-CN源文；源文也为空则省略键。namespace不存在返回404，请求故障不缓存为成功空数据，应用可用内置文案兜底。