Crowdin iOS SDK

Crowdin iOS SDK 立即将来自 Crowdin 项目的所有新翻译应用到应用中。因此，无需通过 App Store 更新此应用程序以获取带有本地化的新版本。

SDK 提供以下功能

• 空中内容交付 – 项目中需要时，将本地化内容发送到应用程序。
• 实时预览 – 在编辑器中完成的全部翻译均可在您的应用程序版本中实时显示。查看已翻译的内容和您当前正在输入的内容。
• 屏幕截图 – 应用程序中制作的所有屏幕截图都可以自动附带带有标记的源字符串发送到您的 Crowdin 项目。

目录

• 要求
• 依赖项
• 安装
• 设置
• 高级特性
  • 实时预览
  • 屏幕截图
• 说明
• 文件导出模式
• 贡献
• 寻求帮助
• 安全
• 作者
• 许可证

要求

• Xcode 10.2
• Swift 4.2
• iOS 9.0

依赖项

• Starscream - 为 iOS 和 macOS 提供的 Swift Websockets。

安装

CocoaPods

1. CocoaPods

   要使用 CocoaPods 安装 Crowdin iOS SDK，请确保您已在本地上安装了 CocoaPods。如果尚未安装，请使用以下命令进行安装：sudo gem install cocoapods。

   详细信息可在此处找到：这里。

   将以下行添加到您的 Podfile 中

   pod 'CrowdinSDK'

2. CocoaPods 规范仓库

   target 'MyApp' do
     pod 'CrowdinSDK'
   end

3. 与 App 扩展一起工作

   在 pod install 结果中，如果您应用中嵌入了目标扩展，您可能会遇到一些构建问题。

   示例错误

   'shared' (Swift) / 'sharedApplication' (Objective-C) 不可用：在 iOS (App 扩展) 中不可用 - 在适当的情况下，请使用基于视图控制器的解决方案。

   在这种情况下，您需要在 Podfile 中添加一个 post_install 脚本

   post_install do |installer|
   
     extension_api_exclude_pods = ['CrowdinSDK']
   
     installer.pods_project.targets.each do |target|
   
         # the Pods contained into the `extension_api_exclude_pods` array
         # have to get the value (APPLICATION_EXTENSION_API_ONLY) set to NO
         # in order to work with service extensions
   
         if extension_api_exclude_pods.include? target.name
           target.build_configurations.each do |config|
             config.build_settings['APPLICATION_EXTENSION_API_ONLY'] = 'NO'
           end
         end
       end
   end

   然后再次运行 pod install 以修复它。

将 CrowdinSDK 添加到 Podfile 后，在项目目录中运行 pod install，打开 App.xcworkspace 并构建它。

Swift 包管理器

一旦您已设置好 Swift 包，将 CrowdinSDK 添加为依赖项就像将它添加到您的 Package.swift 的依赖项值一样简单。

‼️Swift 包管理器支持从版本 1.4.0 开始。‼️

dependencies: [
    .package(url: "https://github.com/crowdin/mobile-sdk-ios.git", from:"1.4.0")
]

设置

要配置 iOS SDK 集成，您需要：

• 将您的 strings/stringsdict 本地化文件上传至 Crowdin。如果您已有准备好的翻译，也可以上传它们。
• 在 Crowdin 中设置分发。
• 设置 SDK 并启用空中内容传输功能。

分发 是一个 CDN 保险库，用于镜像您的项目已翻译的内容，并与 iOS 应用集成所必需的。

要管理分发，请打开所需的项目并进入 空中内容传输。您可以根据需要创建尽可能多的分发，并为每个分发选择不同的文件。每次您想要将新翻译发送到应用时，都需要点击必要分发旁边的 发布 按钮。

1. 在您的 Crowdin 项目中启用 空中内容传输，以便应用程序可以从 CDN 保险库中提取翻译。

2. 为了开始使用 CrowdinSDK，您需要在 AppDelegate 或 Info.plist 中对其进行初始化。

说明

• 翻译下载将在应用程序启动后异步进行。在下次启动应用程序之后，将使用下载的翻译，否则将使用先前缓存的翻译（如果缓存不存在，则使用本地翻译）。
• CDN 功能不更新本地化文件。如果您想要将新翻译添加到本地化文件中，您需要自行操作。
• SDK 接收到翻译后，它将以应用程序文件的形式存储在设备上，以最小化下一次应用启动时的请求。存储时间可以通过使用 intervalUpdatesEnabled 选项进行配置。
• CDN 缓存所有发布版本的翻译，最多 15 分钟，即使新翻译在 Crowdin 中发布，CDN 也可能延迟返回它。

使用 AppDelegate 设置

打开 AppDelegate.swift 文件并添加

import CrowdinSDK

在 application 方法中添加

let crowdinProviderConfig = CrowdinProviderConfig(hashString: "{your_distribution_hash}",
  sourceLanguage: "{source_language}")

CrowdinSDK.startWithConfig(crowdinSDKConfig, completion: {
    // SDK is ready to use, put code to change language, etc. here
})

@import CrowdinSDK

#import<CrowdinSDK/CrowdinSDK.h>

CrowdinProviderConfig *crowdinProviderConfig = [[CrowdinProviderConfig alloc] initWithHashString:@"" sourceLanguage:@""];
CrowdinSDKConfig *config = [[[CrowdinSDKConfig config] withCrowdinProviderConfig:crowdinProviderConfig]];

[CrowdinSDK startWithConfig:config completion:^{
    // SDK is ready to use, put code to change language, etc. here
}];

$(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME)

使用Info.plist设置

打开Info.plist文件并添加

CrowdinDistributionHash - 当前项目的Crowdin CDN哈希值（字符串值）。

CrowdinSourceLanguage - 服务器上当前项目的源语言代码（字符串值，ISO 639-1编码）。

在AppDelegate中调用start方法：Swift语言中使用CrowdinSDK.start()}，Objective-C中使用[CrowdinSDK start]。

注意！使用此设置方法，您将无法设置额外的截图和实时预览项目功能。

SwiftUI支持

目前SwiftUI没有自动支持。只有在传递本地化字符串时使用NSLocalizedString(“key”, comment: “comment”)时它才会工作。这意味着您需要更新SwiftUI应用程序中所有本地化字符串。为了更方便地使用，您可以使用我们提供的本地化String扩展：“key”.cw_localized。

示例

Text(NSLocalizedString(“key”, comment: “comment”))

或

Text(“key”.cw_localized)

在添加SwiftUI支持之后，您只需简单地移除对cw_localized方法的调用。

高级功能

实时预览

在编辑器中完成的全部翻译都可以实时地显示在应用程序中。查看已经完成的翻译以及您目前正在输入的翻译。

将以下代码添加到您的Podfile

use_frameworks!
target 'your-app' do
    pod 'CrowdinSDK'
    pod 'CrowdinSDK/LoginFeature' // Required for Real-Time Preview
    pod 'CrowdinSDK/RealtimeUpdate' // Required for Real-Time Preview
    pod 'CrowdinSDK/Settings' // Optional. To add 'settings' floating button
end

打开AppDelegate.swift文件，在application方法中添加

let crowdinProviderConfig = CrowdinProviderConfig(hashString: "{your_distribution_hash}",
    sourceLanguage: "{source_language}")

var loginConfig: CrowdinLoginConfig
do {
    loginConfig = try CrowdinLoginConfig(clientId: "{client_id}",
       clientSecret: "{client_secret}",
       scope: "project",
       redirectURI: "{redirectURI}",
       organizationName: "{organization_name}")
} catch {
    print(error)
    // CrowdinLoginConfig initialization error handling, typically for empty values and for wrong redirect URI value.
}

let crowdinSDKConfig = CrowdinSDKConfig.config().with(crowdinProviderConfig: crowdinProviderConfig)
    .with(loginConfig: loginConfig)
    .with(settingsEnabled: true)
    .with(realtimeUpdatesEnabled: true)

CrowdinSDK.startWithConfig(crowdinSDKConfig, completion: {
    // SDK is ready to use, put code to change language, etc. here
})

CrowdinProviderConfig *crowdinProviderConfig = [[CrowdinProviderConfig alloc] initWithHashString:@"" sourceLanguage:@""];

NSError *error;
CrowdinLoginConfig *loginConfig = [[CrowdinLoginConfig alloc] initWithClientId:@"{client_id}" clientSecret:@"{client_secter}" scope:@"project" organizationName:@"{organization_name}" error:&error];

if (!error) {
    CrowdinSDKConfig *config = [[[CrowdinSDKConfig config] withCrowdinProviderConfig:crowdinProviderConfig] withLoginConfig:loginConfig];

    [CrowdinSDK startWithConfig:config completion:^{
       // SDK is ready to use, put code to change language, etc. here
    }];
} else {
    NSLog(@"%@", error.localizedDescription);
    // CrowdinLoginConfig initialization error handling, typically for empty values and for wrong redirect URI value.
}

最后一步是在您的应用程序中处理授权回调

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    CrowdinSDK.handle(url: url)
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    return [CrowdinSDK handleWithUrl:url];
}

如果您使用的是SceneDelegate，您需要在SceneDelegate类的实现方法中处理回调

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    CrowdinSDK.handle(url: url)
}

- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
    return [CrowdinSDK handleWithUrl:url];
}

屏幕截图

如果您想将应用程序中创建的所有屏幕截图自动发送到您的Crowdin项目，并带有标记的字符串，请启用此选项。这将为翻译人员提供附加的上下文。

将以下代码添加到您的Podfile

use_frameworks!
target 'your-app' do
    pod 'CrowdinSDK'
    pod 'CrowdinSDK/LoginFeature' // Required for Screenshots
    pod 'CrowdinSDK/Screenshots' // Required for Screenshots
    pod 'CrowdinSDK/Settings' // Optional. To add 'settings' button
end

打开AppDelegate.swift文件，在application方法中添加

let crowdinProviderConfig = CrowdinProviderConfig(hashString: "{your_distribution_hash}",
    sourceLanguage: "{source_language}")

var loginConfig: CrowdinLoginConfig
do {
   loginConfig = try CrowdinLoginConfig(clientId: "{client_id}",
       clientSecret: "{client_secret}",
       scope: "project.screenshot",
       redirectURI: "{redirectURI}",
       organizationName: "{organization_name}")
} catch {
    print(error)
    // CrowdinLoginConfig initialization error handling, typically for empty values and for wrong redirect URI value.
}

let crowdinSDKConfig = CrowdinSDKConfig.config().with(crowdinProviderConfig: crowdinProviderConfig)
    .with(screenshotsEnabled: true)
    .with(loginConfig: loginConfig)
    .with(settingsEnabled: true)

CrowdinSDK.startWithConfig(crowdinSDKConfig, completion: {
    // SDK is ready to use, put code to change language, etc. here
})

CrowdinProviderConfig *crowdinProviderConfig = [[CrowdinProviderConfig alloc] initWithHashString:@"" sourceLanguage:@""];

NSError *error;
CrowdinLoginConfig *loginConfig = [[CrowdinLoginConfig alloc] initWithClientId:@"{client_id}" clientSecret:@"{client_secter}" scope:@"project.screenshot" organizationName:@"{organization_name}" error:&error];

if (!error) {
    CrowdinSDKConfig *config = [[[CrowdinSDKConfig config] withCrowdinProviderConfig:crowdinProviderConfig] withLoginConfig:loginConfig];

    [CrowdinSDK startWithConfig:config completion:^{
        // SDK is ready to use, put code to change language, etc. here
    }];
} else {
    NSLog(@"%@", error.localizedDescription);
    // CrowdinLoginConfig initialization error handling, typically for empty values and for wrong redirect URI value.
}

最后一步是在您的应用程序中处理授权回调

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    CrowdinSDK.handle(url: url)
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    return [CrowdinSDK handleWithUrl:url];
}

如果您使用的是SceneDelegate，您需要在SceneDelegate类的实现方法中处理回调

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    CrowdinSDK.handle(url: url)
}

- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
    return [CrowdinSDK handleWithUrl:url];
}

您还可以定义（可选）自己的处理程序来截取屏幕截图（例如，在应用程序中单击某个按钮）

CrowdinSDK.captureScreenshot(name: String(Date().timeIntervalSince1970)) {
    print("Screenshot captured")
} errorHandler: { error in
    print("Screenshot capture failed with error - " + error?.localizedDescription)
}

甚至捕获单独的UIView的屏幕截图。

备注

1. 配置翻译更新间隔

   默认情况下，SDK每15分钟查找一次新的翻译。您可以在应用程序中以定义的时间间隔更新翻译。要启用此功能，请将pod CrowdinSDK/IntervalUpdate 添加到您的pod文件。

   pod 'CrowdinSDK/IntervalUpdate'

   然后在 CrowdinSDKConfig 中启用此选项

   .with(intervalUpdatesEnabled: true, interval: {interval})

   interval - 指定翻译更新时间间隔（以秒为单位）。最小允许间隔为15分钟。

2. R-Swift应用程序也由Crowdin iOS SDK支持。

3. 要无无论设备的区域设置如何动态更改SDK的目标语言，可以使用以下方法

   CrowdinSDK.enableSDKLocalization(true, localization: “<language_code>”)

   <language_code> - 在ISO 639-1格式中的目标语言代码。

4. 目前，iOS SDK不支持语言映射。

5. Crowdin iOS SDK提供了详细的调试模式 - 设置浮动按钮模块中的“日志”选项卡以及登录XCode控制台。要启用控制台日志记录，请将以下选项添加到您的 CrowdinSDKConfig

   .with(debugEnabled: true)

6. 日志回调。Crowdin SDK收集SDK进行的所有操作的日志消息（登录/注销、下载语言、API调用）。此回调在创建新的日志时返回日志文本。要订阅接收日志消息，请添加新的回调如下

   CrowdinSDK.setOnLogCallback { logMessage in
      print("LOG MESSAGE - \(logMessage)")
   }

文件导出模式

您可以使用“文件设置”来设置文件导出模式并检查现有的模式。以下占位符用于iOS集成

贡献力量

如果您想贡献力量，请阅读贡献力量指南。

寻求帮助

如果您发现任何问题或想提出一个功能建议，请随时在Github上提交问题到问题页面。

需要帮助使用Crowdin iOS SDK或有任何问题？联系客户服务。

安全

Crowdin iOS SDK CDN功能注重安全性，这意味着尽可能减少最终用户可能获得的访问权限。当您决定使用Crowdin iOS SDK时，请确保您已将以下信息提供给您的最终用户。

• 我们利用亚马逊网络服务（AWS）的优势来构建我们的计算基础设施。AWS拥有ISO 27001认证，并已完成多项SSAE 16审计。所有翻译都存储在AWS服务器上。
• 当您使用Crowdin iOS SDK CDN时-翻译将上传到Amazon CloudFront以提供给应用程序并提高下载速度。请注意，您的用户在没有任何额外认证的情况下下载翻译。
• 我们使用加密来在传输过程中保持您的数据私密。
• 我们不存储有关最终用户的任何个人信息（PII），但您可以在您的应用程序中开发退出选项，以确保您的用户完全控制。
• 自动截图和实时预览功能应仅供开发团队和翻译团队使用。这些功能不应编译到您的应用程序的生产版本中，因此不会以任何方式影响最终用户的隐私。

作者

• Serhii Londar, [email protected]

许可证

The Crowdin iOS SDK is licensed under the MIT License. 
See the LICENSE file distributed with this work for additional 
information regarding copyright ownership.

Except as contained in the LICENSE file, the name(s) of the above copyright 
holders shall not be used in advertising or otherwise to promote the sale, 
use or other dealings in this Software without prior written authorization.