# Loxily Localize iOS SDK

Loxily Localize 提供了一套完整的本地化翻译解决方案，帮助客户管理应用本地化文件，让你摆脱 App 版本更新的束缚，以更加灵活的方式管理你的本地化文件。

**在开始接入之前，请确保你已经在 [Loxily Localize](https://www.ilocalize.com) 注册了你的应用信息。**

## 最新版本

**当前版本：`1.2.2`**（2026-05-29 发布）

- XCFramework 包（推荐，真机 + 模拟器全架构）：`release/loxilyLocalizeSDK-1.2.2/loxilyLocalizeSDK.xcframework`
- 发布压缩包：`release/loxilyLocalizeSDK-1.2.2.zip`
- 自取构建：在仓库根目录运行 `./build_framework_xcframework.sh`，产物输出到 `release/loxilyLocalizeSDK-<VERSION>/`
- 运行时版本号通过 `GGSdkConfigSetting.sharedInstance.sdkVersion` 读取

**1.2.2 改动**：稳定性补丁，针对 Crashlytics issue `be8648ac`（后台 + 断网叠加场景下 `CFWriteStreamWrite EXC_BREAKPOINT`）追加三层加固。完整说明见 [docs/STABILITY_NOTES.md](docs/STABILITY_NOTES.md) §1.6。

## SDK 接入

#### Framework 集成（推荐）

1、下载 `loxilyLocalizeSDK.framework` 文件；

2、将 `loxilyLocalizeSDK.framework` 拖拽到你的 Xcode 项目中；

3、在项目设置中配置：
   - 在 `General` → `Frameworks, Libraries, and Embedded Content` 中，将 `loxilyLocalizeSDK.framework` 设置为 `Do Not Embed`（静态库）
   - 在 `Build Settings` → `Other Linker Flags` 中添加 `-ObjC`

4、在需要使用的地方导入头文件：
```objc
#import <loxilyLocalizeSDK/loxilyLocalizeSDK.h>
```

#### 手动构建 Framework

如果需要从源码构建 Framework：

1、打开项目：
```bash
open iLocalizeSDK.xcodeproj
```

2、选择 Scheme `iLocalizeSDK`，分别构建真机和模拟器版本；

3、使用 `lipo` 命令合并两个版本的 Framework；

4、将合并后的 Framework 集成到项目中。

## SDK API

#### SDK 初始化

在项目的 `AppDelegate` 中调用如下方法完成初始化：

```objc
#import <loxilyLocalizeSDK/loxilyLocalizeSDK.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [LoxilyLocalize initWithAppKey:@"YOUR APPKEY"
                     language:@"zh_CN"
          isInternationalizing:YES
                      isDebug:NO];
    return YES;
}
```

基本参数说明如下：

|         参数         |                             描述                             |            示例             |
| :------------------: | :----------------------------------------------------------: | :-------------------------: |
|        appKey        | 应用唯一标识，[在 Loxily Localize 后台获取](https://www.ilocalize.com) | 4b290d495c67075db7b80b845d80e244 |
|       language       |                     本地化的目标语言代码                     |            zh_CN            |
| isInternationalizing |               标记应用包渠道，海外 / 中国大陆                |        YES / NO         |
|       isDebug        |             应用的 buildType，标记是否为调试模式             |        YES / NO         |

此外，你还可以在**初始化后**添加如下代码，为初始化添加回调。推荐使用 block 形态 `setTranslationPreparedBlock:`，失败时携带具体 `errorMsg`：

```objc
[LoxilyLocalize setTranslationPreparedBlock:^(BOOL success, NSString * _Nullable errorMsg) {
    if (success) {
        // 翻译文件准备完成
    } else {
        // 翻译文件准备失败，errorMsg 给出具体原因
        // 例如：init failed: version 'x.y.z' (buildType=2) not published for appKey 'xxx'
        //      init failed (code=404): xxx
        //      init request network error / language file download error
        NSLog(@"Loxily 初始化失败：%@", errorMsg);
    }
}];
```

> 旧的 C 函数指针形态 `setTranslationPreparedCallback:` 仍可用但已 `__deprecated_msg`，**不携带 `errorMsg`**，建议迁移到 block 形态。

#### 获取目标文本

当涉及到具体的本地化翻译时，你将使用到 `LoxilyLocalize#getStringWithCode:` 方法。

你可以在具体的业务场景下，调用如下方法：

其中，**`getStringWithCode:` 的入参为词条对应的 code 值**，需要与上传 [Loxily Localize 后台](https://www.ilocalize.com)的本地化文件统一。

```objc
NSString *result = [LoxilyLocalize getStringWithCode:@"110100"];
NSString *resultMaybeDefault = [LoxilyLocalize getStringWithCode:@"110100" defaultString:@"This is default text."];
```

#### 切换语言

当应用涉及到多语言切换时，你需要在切换语言时调用如下方法：

```objc
[LoxilyLocalize updateLanguage:@"zh_CN"];
```

像 [SDK 初始化](#sdk-初始化)一样，当切换目标语言时，同一个 `setTranslationPreparedBlock:` 回调也会被触发：

```objc
[LoxilyLocalize setTranslationPreparedBlock:^(BOOL success, NSString * _Nullable errorMsg) {
    if (success) {
        // 语言切换完成，翻译文件已准备
    } else {
        // 语言切换失败，errorMsg 给出具体原因
        NSLog(@"Loxily 语言切换失败：%@", errorMsg);
    }
}];
```

#### 调试日志开关

为了方便调试、定位接入过程中可能出现的问题，SDK 提供了方法来控制日志信息的打印。

```objc
[LoxilyLocalize setLogEnable:YES];
[LoxilyLocalize initWithAppKey:@"YOUR APPKEY" language:@"zh_CN" isInternationalizing:YES isDebug:NO];
```

打开开关后，你就可以在 Xcode 控制台中收到某些可能对调试有帮助的日志信息。

## License

```
Copyright 2015 ShareFun Network Limited.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```
