translation - PythonIDE Docs

设备端文本翻译（Apple Translation 框架）：离线翻译、查询支持语言。

边界：需 iOS 支持 Translation 框架；首次翻译可能下载语言包。仅文本翻译，不含实时语音同传。

#模块概览

项	说明
导入	`import translation`
适合做什么	笔记翻译、多语言 UI 文案、离线翻译
调用时机	`translate()` 放在按钮回调
推荐顺序	`is_available()` → `supported_languages()` → `translate()`
语言码	BCP-47，如 `en`、`zh-Hans`、`ja`

#快速开始

python

import translation

if not translation.is_available():
    print("Translation 不可用")
else:
    print(translation.supported_languages())
    text = translation.translate("你好，世界", target="en")
    print(text)

指定源语言：

python

import translation

text = translation.translate("Bonjour", target="zh-Hans", source="fr")
print(text)

#AppUI 示例

python

import appui
import translation

state = appui.State(
    available="—",
    source="你好，世界",
    target_lang="en",
    result="—",
)


def refresh_available():
    state.available = "是" if translation.is_available() else "否"


def do_translate():
    refresh_available()
    if state.available != "是":
        state.result = "Translation 不可用"
        return

    try:
        state.result = translation.translate(state.source, target=state.target_lang)
    except translation.TranslationError as exc:
        state.result = str(exc)


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("翻译", [
                appui.TextEditor(text=state.source).frame(min_height=80),
                appui.TextField("目标语言", text=state.target_lang),
                appui.Button("翻译", action=do_translate)
                .button_style("bordered_prominent"),
            ]),
            appui.Section("结果", [
                appui.LabeledContent("可用", value=state.available),
                appui.Text(state.result).foreground_color("secondaryLabel"),
            ]),
        ]).navigation_title("翻译")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`is_available()`	Translation 是否可用 → `bool`
`supported_languages()`	支持的语言码列表
`translate(text, target='en', source=None)`	翻译文本 → `str`
`TranslationError`	翻译失败异常

#translate

translate(text, target='en', source=None) — source 省略时自动检测源语言。

python

translation.translate("你好", target="en")
translation.translate("Hello", target="zh-Hans", source="en")

#常见错误

错误写法	后果	修正
未检查 `is_available()`	抛 `TranslationError`	先判断可用性与系统版本
无效语言码	翻译失败	用 `supported_languages()` 核对
在 `body()` 里自动翻译	每次刷新重复请求	放进按钮回调
超长文本一次翻译	可能超时或截断	分段翻译

#相关文档

文档	用途
foundation_models	端侧文本生成（iOS 26+）
speech	语音合成

#预期效果

运行示例后，界面应出现文档描述的目标结果；若与预期不符，先看「失败路径」并按返回值或日志排查。