Godot SDK

Loxily Godot SDK 是一个 纯 GDScript 的 Godot 4 插件。启用后用统一的 LoxilyLocalize.* API 完成运行时取词、语言切换、AI 截图审校、玩家共创、AI 对话助手，无原生依赖——桌面 / 移动 / Web 所有导出平台通吃。

集成需配合 Loxily 本地化平台 账号（appKey）。SDK 只是客户端，译文与发布在平台侧管理。

这是哪条集成路径？

• Godot 项目 → 用本页的 Godot 插件（纯 GDScript，一套全平台通吃）。
• Unity 项目 → 用 Unity SDK。
• 原生 iOS / Android / Cocos2dx 等 → 用 iOS SDK / Android SDK。

要求

• Godot 4.1+
• 一个 Loxily 平台账号与 appKey
• 无需任何原生插件或第三方依赖

集成步骤

1. 安装插件

方式一：Godot Asset Store（推荐）

在编辑器 AssetLib 标签页搜索 Loxily Localize，点开后 Download → Install 即可； 也可以在浏览器打开商店页面查看详情、直接下载 zip：

🛒 Loxily Localization SDK · Godot Asset Store

方式二：手动复制

把 addons/loxily_localize/ 目录整个拷进你项目的 addons/ 下即可。

2. 启用插件

菜单 项目 → 项目设置 → 插件，勾选 Loxily Localize。

启用后会自动注册一个名为 LoxilyLocalize 的 Autoload 单例，全局可用，无需手动实例化。

3. 在 GDScript 中使用

func _ready() -> void:
    # 1) 语言包就绪回调（主线程）
    LoxilyLocalize.translation_prepared.connect(func(success):
        if success:
            print(LoxilyLocalize.get_string("100000001", "default")))

    # 2) 初始化（is_internationalizing=true 走国际站）
    LoxilyLocalize.init("YOUR_APP_KEY", "en", true)

关于版本号（重要）

SDK 以 app_version 作为取译文的依据。默认自动读项目版本号 （项目设置 → 应用 → 配置 → 版本，即 application/config/version），也可在 init 前手动覆盖：

LoxilyLocalize.app_version = "1.2.3"

游戏的真实版本号需落在平台已发布译文的版本区间内，否则取不到译文（后端按区间匹配）。

主要 API

# ── 初始化 / 就绪信号 ──
LoxilyLocalize.init(app_key: String, language: String, is_internationalizing := true, is_build_debug := false)
signal translation_prepared(success: bool)
LoxilyLocalize.is_prepared() -> bool
LoxilyLocalize.get_language() -> String

# ── 取词（args 填充 {0}、{1} … 占位符）──
LoxilyLocalize.get_string(code: String, default_str := "", args := []) -> String
LoxilyLocalize.get_page_string(page_id: String, code: String, default_str := "", args := []) -> String

# ── 切语言（切完等 translation_prepared 再取词）──
LoxilyLocalize.update_language(language: String)

# ── 用户信息（共创需要 user_id）──
LoxilyLocalize.update_user_info({ "user_id": "uid", "user_tags": "vip1" })

# ── AI 对话助手 / 悬浮气泡 / 审校页（内置 UI）──
LoxilyLocalize.show_agent_bubble()          # 悬浮按钮 → 弹 Chat / Review 菜单
LoxilyLocalize.hide_agent_bubble()
LoxilyLocalize.open_agent_chat()            # 流式 AI 对话页
LoxilyLocalize.open_review_panel()          # AI 审校当前屏，列出问题
LoxilyLocalize.evaluate_string("100100")    # 单个词条的评分 + 建议面板
LoxilyLocalize.suggest_translation(PackedStringArray(["100100"]))

# ── 无 UI 变体（自绘界面用）──
signal review_completed(success: bool, items: Array, summary: String)
LoxilyLocalize.review_current_screen(page_id := "", image := null)   # 自动截当前屏
LoxilyLocalize.submit_suggestions(
    [{ "string_id": "100000001", "rating": 5, "suggested_translation": "我的建议" }],
    func(success, rating_count, suggestion_count, err): pass)

# ── 错误 / 崩溃上报 ──
LoxilyLocalize.report_error(message: String, stacktrace := "")
LoxilyLocalize.report_crash(exception_class: String, message: String, stacktrace := "")

LoxilyLocalize.set_log_enable(enable: bool)   # 日志开关

AI 助手 UI

内置的对话页、审校结果页、共创面板、悬浮气泡都是 Godot 原生 Control 自适应浮层：手机竖屏接近全屏、 桌面宽屏居中限宽，跟随窗口大小实时重排。它们挂在 SDK 内部的高层 CanvasLayer 上，永远盖在游戏画面最上层。

• open_agent_chat() —— 真·SSE 流式对话，逐字打字，多轮上下文。
• open_review_panel() —— 触发 AI 审校当前屏，按 severity 上色列卡片，可一键"找 AI 讨论"跳进对话页。
• evaluate_string() / suggest_translation() —— 玩家评分 + 提交译文建议。
• show_agent_bubble() —— 可拖拽的悬浮助手按钮，点开菜单进对话/审校。

遥测（自动）

初始化后自动处理，无需接入方干预：

• 日活设备（DAU）：每 UTC 日上报一次（稳定设备标识持久化在 user://）。
• 词条曝光采样：按平台下发的采样率统计 get_string 命中，进后台 / 下次 init 时上报。
• 静默截图抽样：平台按需下发目标词条，命中屏幕时一会话截一张上传。

非崩溃错误与崩溃可从你自己的异常处理里主动上报（Godot 无全局 GDScript 异常钩子）：

LoxilyLocalize.report_error("加载存档失败", str(get_stack()))

缓存与增量更新

语言包缓存在 user://。有可用增量补丁时走增量更新（下载补丁打到本地全量上，并用 MD5 校验结果）， 校验不过则自动回退全量下载——永不损坏译文。

许可证

专有软件，© 2026 Loxily，保留所有权利。 本 SDK 为授权使用而非出售:你可将其集成进自己的游戏/应用 并随之分发,但不得单独转售、再分发或逆向工程(详见 SDK 包内 LICENSE.md 的 EULA)。SDK 是 Loxily 本地化服务的客户端,使用服务需要 Loxily 账号与 appKey,并受服务条款约束。

常见问题

Q：每次发游戏版本要更新插件吗？ 不用。插件集成一次固定不动；版本号走游戏自己的发布流程，SDK 自动读 application/config/version。

Q：Web 导出能用吗？ 能。纯 GDScript + HTTPRequest/HTTPClient，不依赖线程或原生库,所有导出平台一致。

Q：AI 对话为什么要用底层 HTTPClient？ Godot 的 HTTPRequest 会缓冲整个响应、不支持流式；对话页要逐字打字,所以用 HTTPClient 手动解析 SSE。