Unity SDK

Loxily Unity SDK 是一个跨平台（iOS / Android）的 Unity 集成包。导入后用统一的 LoxilyLocalize.* C# API 完成运行时取词、语言切换、AI 截图审校、玩家共创，无需分别对接两端原生 SDK。
集成需配合 Loxily 本地化平台账号（appKey）。SDK 只是客户端，译文与发布在平台侧管理。

这是哪条集成路径？

Unity 项目 → 用本页的 Unity SDK 包（推荐，一套 C# 双端通吃）。
原生 iOS / Cocos2dx 等非 Unity 工程 → 用 iOS SDK / Android SDK。

要求

Unity 2020.3+（iOS 必须 IL2CPP）
iOS 12+ / Android minSdk 22+
Android 依赖解析建议装 EDM4U（External Dependency Manager for Unity）
一个 Loxily 平台账号与 appKey

集成步骤

1. 从 Unity Asset Store 导入

推荐用 Unity Asset Store 集成——由 Package Manager 统一管理版本,后续升级一键更新,无需手动换包。

① 打开商品页,加入 My Assets

在浏览器打开 Loxily Localization SDK 商品页(需登录你的 Unity 账号):

🛒 Loxily Localization SDK · Unity Asset Store

点右侧 Add to My Assets → 接受 EULA，按钮会变成 Open in Unity。这一步把资源加进你账号的 My Assets，之后在编辑器里就能拉取。

Asset Store 商品页 — Add to My Assets

商品页正在审核

Loxily SDK 提交后处于 Unity 审核队列中（Pending），审核通过正式上架后上面的链接才可访问，在此之前打开会显示 404。审核通过后本页链接即自动生效。

② 在 Unity 里下载并导入

回到 Unity 编辑器，菜单 Window → Package Manager → 左上 Packages 下拉选 My Assets → 在列表里找到 Loxily Localization SDK → 右下角 Download，下载完点 Import。

Package Manager → My Assets → Loxily Localization SDK

③ 全选导入

在弹出的 Import Unity Package 窗口保持全选，点 Import。

Import Unity Package 窗口 — 全选后 Import

包内含：C# 桥接层（Runtime/）、iOS 桥与 xcframework（Plugins/iOS/）、 Android 依赖声明与 iOS 构建脚本（Editor/）、示例（Demo/）。

无法访问 Asset Store？也可以直接下载离线 .unitypackage，见文末离线安装包（备用）。

2. Android：解析依赖

Android 的 SDK 本体（com.loxily:android-localize-sdk aar）通过 EDM4U 从 Maven 拉取：

菜单 Assets → External Dependency Manager → Android Resolver → Resolve。

不用 EDM4U 也可手动在 mainTemplate.gradle 加 implementation 'com.loxily:android-localize-sdk:1.7.7'，并确保 settingsTemplate.gradle 仓库列表里有 mavenCentral()。

3. iOS：无需手动配置 `-ObjC`

包内的构建后处理脚本会自动给 Xcode 工程的 UnityFramework target 加 -ObjC。

为什么需要 -ObjC

iOS SDK 是静态库且用了 Objective-C 分类（category）（如 NSString 的 gg_isEmpty）。链接静态库时分类不产生新符号会被丢弃，运行时崩 unrecognized selector sent to instance。 -ObjC 强制加载所有 ObjC 类与分类。SDK 静态库链接在 UnityFramework target，所以 -ObjC 必须加在它身上（脚本已自动处理；手动加请加到 framework target，不是 app target）。

4. 在 C# 代码中使用

csharp

using UnityEngine;

public class MyLocalization : MonoBehaviour
{
    void Start()
    {
        // 1) 初始化完成回调（语言包就绪后触发，主线程）
        LoxilyLocalize.SetOnTranslationPreparedCallback(success => {
            if (success)
                Debug.Log(LoxilyLocalize.GetString("100000001", "default"));
        });

        // 2) 初始化（isInternationalizing=true 走国际站）
        LoxilyLocalize.Init("YOUR_APP_KEY", "en", true);
    }
}

关于版本号（重要）

SDK 以 appVersion 作为取译文的依据，自动读应用版本号，集成方不用手设、不用每次发版改 SDK 包：

平台	读取来源
iOS	`CFBundleShortVersionString`（= Player Settings → Version）
Android	`packageInfo.versionName`（Unity 直打 = Player Settings → Version；原生集成 = gradle `versionName`）

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

主要 API

csharp

// 初始化 / 就绪回调
LoxilyLocalize.Init(string appKey, string language, bool isInternationalizing, bool isBuildDebug = false);
LoxilyLocalize.SetOnTranslationPreparedCallback(success => { ... });

// 取词
string LoxilyLocalize.GetString(string code, string defaultStr = null);
string LoxilyLocalize.GetPageString(string pageId, string code, string defaultStr = null);

// 切语言（切完等 OnPrepared 再取词）
LoxilyLocalize.UpdateLanguage(string language);

// 用户信息（共创需要 userId）
LoxilyLocalize.UpdateUserInfo(new LoxilyLocalizeUserConfig.Builder()
    .SetUserId("uid").SetUserTags("vip1").Build());

// AI 截图审校
LoxilyLocalize.ReviewCurrentScreen(string[] stringIds, byte[] imageBytes);

// 玩家共创建议（内置 UI）
LoxilyLocalize.SuggestTranslation(string[] stringIds, byte[] imageBytes);

// 共创建议无 UI 程序化提交
LoxilyLocalize.SubmitTranslationSuggestions(
    new[] { new LoxilyTranslationSuggestion("100000001", 5, "我的建议") },
    (success, ratingCount, suggestionCount, err) => { ... });

// AI Agent 悬浮气泡
LoxilyLocalize.ShowAgentBubble();
LoxilyLocalize.HideAgentBubble();

LoxilyLocalize.SetLogEnable(bool enable);   // 日志开关

打包与调试要点

iOS 模拟器：Player Settings → iOS → Target SDK 选 Simulator SDK； iOS 真机：选 Device SDK。两者工程互不兼容，切换后需重新 Build。
真机签名报 errSecInternalComponent 多为钥匙串/重复证书问题；Command CodeSign failed 在 framework 上报 unrecognized selector 则是 -ObjC 没加到 framework target（见上）。
部分 Unity/团结引擎版本在 iOS 模拟器上引擎启动（frameworkWarmup）不稳，建议真机验证。

离线安装包（备用）

优先走 Unity Asset Store——版本由 Package Manager 托管、升级一键更新。仅当无法访问 Asset Store（网络受限、账号问题等）时，才用离线包：下载后双击，或菜单 Assets → Import Package → Custom Package 导入。

📦 下载 Loxily Unity SDK（.unitypackage）

离线包内容与 Asset Store 版本一致，但升级需手动重新下载导入，不像 Asset Store 那样在 Package Manager 里一键更新。

手动 / 高级集成（可选）

绝大多数项目用上面的包即可。但如果你有自定义构建流水线（不走 UPM / .unitypackage）、工程里已有大量原生集成、或需要把 SDK 塞进现成的原生壳工程，可以自己接桥—— 机制和包内完全一样，只是手动重现一遍：

iOS

把 loxilyLocalizeSDK.xcframework 作为 Unity iOS 插件放入工程（或在导出的 Xcode 工程里手动添加）。
加入 ObjC 桥 LoxilyLocalizeUnity.mm（导出 extern "C" 入口供 C# [DllImport("__Internal")] 调用）。
手动给链接 SDK 静态库的 target（UnityFramework）加 -ObjC —— 漏了会运行时崩 unrecognized selector。
C# 侧写 [DllImport("__Internal")] extern 声明，签名对齐 .mm 里的 extern "C" 函数。

Android

在 mainTemplate.gradle 手动加 implementation 'com.loxily:android-localize-sdk:1.7.7'， settingsTemplate.gradle 仓库列表保证有 mavenCentral()。
C# 侧用 AndroidJavaClass / AndroidJavaObject 调 Java SDK 的对应方法。

参考实现：包内的 Runtime/LoxilyLocalizeiOSCore.cs、Runtime/LoxilyLocalizeAndroidCore.cs 与 Plugins/iOS/LoxilyLocalizeUnity.mm 就是这套桥的标准实现，手动集成时照着对齐即可。升级时需手动替换这些文件，不像包那样换一个 .unitypackage 就完事——除非有硬性约束，否则优先用包。

常见问题

Q：每次发游戏版本要更新 SDK 包吗？ 不用。SDK 集成一次固定不动；版本号走游戏自己的发布流程，SDK 自动读真实 APK 版本。

Q：必须用桥接吗？能纯 C# 吗？ Unity 是 C#、SDK 是原生（Java/ObjC），中间必然有一层 C#↔原生桥，这是标准做法。本包已把这层封装好，你写纯 C# 调 LoxilyLocalize.* 即可，不用关心底层。

Unity SDK ​

要求 ​

集成步骤 ​

1. 从 Unity Asset Store 导入 ​

2. Android：解析依赖 ​

3. iOS：无需手动配置 -ObjC ​

4. 在 C# 代码中使用 ​

关于版本号（重要） ​

主要 API ​

打包与调试要点 ​

离线安装包（备用） ​

手动 / 高级集成（可选） ​

常见问题 ​