From 132607ba43ef4c2b43a132c427c25e54c7b70dc1 Mon Sep 17 00:00:00 2001 From: Andrii Bodnar Date: Thu, 6 Feb 2025 13:21:56 +0200 Subject: [PATCH] docs: various improvements and clarifications (#313) --- .../advanced-features/real-time-preview.mdx | 13 ++- .../docs/advanced-features/screenshots.mdx | 10 +- .../docs/advanced-features/sdk-controls.mdx | 2 +- website/docs/example.md | 4 +- website/docs/guides/screenshots-automation.md | 2 +- website/docs/installation.md | 20 ++-- website/docs/setup.mdx | 104 +++++++++++++----- 7 files changed, 109 insertions(+), 46 deletions(-) diff --git a/website/docs/advanced-features/real-time-preview.mdx b/website/docs/advanced-features/real-time-preview.mdx index 7aa30fe3..7e9030e9 100644 --- a/website/docs/advanced-features/real-time-preview.mdx +++ b/website/docs/advanced-features/real-time-preview.mdx @@ -14,7 +14,7 @@ The Real-Time Preview feature is designed for development and staging environmen ### Swift -Add the code below to your *Podfile*: +Add the following code to your `Podfile`: ```swift title="Podfile" use_frameworks! @@ -93,18 +93,23 @@ import rtPreviewSetupApiC from '!!raw-loader!../code-samples/rt-preview-api-setu ## Config Options Reference +The SDK configuration is done using the `CrowdinSDKConfig` class. The following options are available: + | Option | Description | Required | Example Value | |--------------------------|------------------------------------------------------------------------------------------------|----------|------------------------| | `hashString` | Distribution Hash | Yes | `"7a0c1...o3b"` | | `sourceLanguage` | Source language code ([ISO 639-1](http://www.loc.gov/standards/iso639-2/php/English_list.php)) | Yes | `sourceLanguage: "en"` | | `organizationName` | Organization domain (Enterprise only) | No | `"mycompany"` | -| `settingsEnabled` | Enable SDK Controls | No | `true` | +| `settingsEnabled` | Enable [SDK Controls](/advanced-features/sdk-controls) | No | `true` | | `realtimeUpdatesEnabled` | Enable Real-Time Preview feature | Yes | `true` | | `accessToken` | Crowdin API access token | No* | `"your_token"` | * Either `accessToken` or OAuth configuration is required. ### OAuth Options + +The `CrowdinLoginConfig` class provides OAuth configuration options: + | Option | Description | Required | Example Value | |----------------|--------------------------------------|----------|--------------------| | `clientId` | OAuth Client ID | Yes* | `"gpY2yT...x3TYB"` | @@ -113,3 +118,7 @@ import rtPreviewSetupApiC from '!!raw-loader!../code-samples/rt-preview-api-setu | `redirectURI` | Custom URL scheme for your app | No | `"crowdintest://"` | *Required only if using OAuth authentication instead of access token. + +:::info +Read more about creating an [OAuth application](https://support.crowdin.com/account-settings/#oauth) in Crowdin. +::: diff --git a/website/docs/advanced-features/screenshots.mdx b/website/docs/advanced-features/screenshots.mdx index 13d35661..6566a620 100644 --- a/website/docs/advanced-features/screenshots.mdx +++ b/website/docs/advanced-features/screenshots.mdx @@ -21,7 +21,7 @@ You can capture and upload tagged screenshots to Crowdin in two ways: ### Swift -To enable the Screenshots feature in your application, add the following configuration to your *Podfile*: +To enable the Screenshots feature in your application, add the following configuration to your `Podfile`: ```swift title="Podfile" use_frameworks! @@ -130,12 +130,14 @@ You can also capture screenshots of specific UIView instances with either method ## Config Options Reference +The SDK configuration is done using the `CrowdinSDKConfig` class. The following options are available: + | Option | Description | Required | Example Value | |----------------------|------------------------------------------------------------------------------------------------|----------|------------------------| | `hashString` | Distribution Hash | Yes | `"7a0c1...o3b"` | | `sourceLanguage` | Source language code ([ISO 639-1](http://www.loc.gov/standards/iso639-2/php/English_list.php)) | Yes | `sourceLanguage: "en"` | | `organizationName` | Organization domain (Enterprise only) | No | `"mycompany"` | -| `settingsEnabled` | Enable SDK Controls | No | `true` | +| `settingsEnabled` | Enable [SDK Controls](/advanced-features/sdk-controls) | No | `true` | | `screenshotsEnabled` | Enable Screenshots feature | Yes | `true` | | `accessToken` | Crowdin API access token | No* | `"your_token"` | @@ -154,6 +156,10 @@ The `CrowdinLoginConfig` class provides OAuth configuration options: * Required only if using OAuth authentication instead of access token. +:::info +Read more about creating an [OAuth application](https://support.crowdin.com/account-settings/#oauth) in Crowdin. +::: + ## Troubleshooting If you get the error: diff --git a/website/docs/advanced-features/sdk-controls.mdx b/website/docs/advanced-features/sdk-controls.mdx index 2c94284a..e4473895 100644 --- a/website/docs/advanced-features/sdk-controls.mdx +++ b/website/docs/advanced-features/sdk-controls.mdx @@ -22,7 +22,7 @@ The SDK controls feature should not be used in a production environment. It is i ### Installation -Add the following code to your Podfile: +Add the following code to your `Podfile`: ```swift title="Podfile" use_frameworks! diff --git a/website/docs/example.md b/website/docs/example.md index 5d956f81..4f0faa0d 100644 --- a/website/docs/example.md +++ b/website/docs/example.md @@ -1,4 +1,4 @@ -# Example project +# Example Project Crowdin [iOS SDK Example project](https://github.com/crowdin/mobile-sdk-ios/tree/master/Example) is a simple todo app that illustrates how you can use Crowdin SDK features with a real iOS app. This app's primary purpose is to show the Crowdin SDK integration process in action and test the possibilities it provides. @@ -8,7 +8,7 @@ In the Crowdin iOS SDK Example app, you can create reminders, add them to groups ## Configuration -You can find all the needed configuration code in [*SceneDelegate.swift*](https://github.com/crowdin/mobile-sdk-ios/blob/master/Example/AppleReminders/SceneDelegate.swift) file. Fill in the following fields using your credentials and run the app. +You can find all the needed configuration code in [`SceneDelegate.swift`](https://github.com/crowdin/mobile-sdk-ios/blob/master/Example/AppleReminders/SceneDelegate.swift) file. Fill in the following fields using your credentials and run the app. ```swift private let distributionHash = "your_distribution_hash" // Crowdin OTA Content Delivery distribution hash diff --git a/website/docs/guides/screenshots-automation.md b/website/docs/guides/screenshots-automation.md index 27ca626e..132e26bb 100644 --- a/website/docs/guides/screenshots-automation.md +++ b/website/docs/guides/screenshots-automation.md @@ -19,7 +19,7 @@ First, add the screenshot feature to your UI Tests target. You can use either Co #### CocoaPods -Add the following to your Podfile: +Add the following to your `Podfile`: ```ruby target 'YourAppUITests' do diff --git a/website/docs/installation.md b/website/docs/installation.md index 241e417e..51b2baf0 100644 --- a/website/docs/installation.md +++ b/website/docs/installation.md @@ -4,9 +4,9 @@ 1. Cocoapods - To install Crowdin iOS SDK via [cocoapods](https://cocoapods.org), make sure you have cocoapods installed locally. If not, install it with following command: `sudo gem install cocoapods`. Detailed instruction can be found [here](https://guides.cocoapods.org/using/getting-started.html). + To install the Crowdin iOS SDK via [cocoapods](https://cocoapods.org), make sure you have cocoapods installed locally. If you don't have it, follow the official [installation guide](https://guides.cocoapods.org/using/getting-started.html) first. - Add the following line to your Podfile: + Then add the following line to your `Podfile`: ```swift title="Podfile" pod 'CrowdinSDK' @@ -21,7 +21,7 @@ ``` :::tip - You can also specify the exact branch of the Crowdin iOS SDK in your Podfile: + You can also specify the exact branch of the Crowdin iOS SDK in your `Podfile`: ```swift pod 'CrowdinSDK', :git => 'https://github.com/crowdin/mobile-sdk-ios.git', :branch => 'dev' @@ -36,7 +36,7 @@ > 'shared' (Swift) / 'sharedApplication' (Objective-C) is unavailable: not available on iOS (App Extension) - Use view controller based solutions where appropriate instead. - In this scenario you'll need to add a `post_install` script to your Podfile + In this scenario you'll need to add a `post_install` script to your `Podfile`: ```swift post_install do |installer| @@ -60,13 +60,13 @@ Then run `pod install` again to fix it. -After you've added *CrowdinSDK* to your Podfile, run `pod install` in your project directory, open `App.xcworkspace` and build it. +After you've added `CrowdinSDK` to your `Podfile`, run `pod install` in your project directory, open `App.xcworkspace` and build it. ## Swift Package Manager -The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the Swift compiler. +The Swift Package Manager is a tool that automates the distribution of Swift code and is integrated with the Swift compiler. -To add CrowdinSDK to your project using SPM: +To add `CrowdinSDK` to your project using SPM: 1. In Xcode, select File > Add Packages... 2. Enter the package repository URL: `https://github.com/crowdin/mobile-sdk-ios.git` @@ -77,7 +77,7 @@ Alternatively, you can add it directly to your Package.swift: ```swift title="Package.swift" dependencies: [ - .package(url: "https://github.com/crowdin/mobile-sdk-ios.git", from: "1.9.0") + .package(url: "https://github.com/crowdin/mobile-sdk-ios.git", from: "1.10.1") ] ``` @@ -85,7 +85,7 @@ dependencies: [ For better version control, you can specify an exact version or version range: ```swift -.package(url: "https://github.com/crowdin/mobile-sdk-ios.git", .upToNextMajor(from: "1.9.0")) +.package(url: "https://github.com/crowdin/mobile-sdk-ios.git", .upToNextMajor(from: "1.10.1")) ``` ::: @@ -95,7 +95,7 @@ For better version control, you can specify an exact version or version range: * Swift 5.0+ * iOS 12.0+ -:::tip +:::info R-Swift applications are also supported by the Crowdin iOS SDK. ::: diff --git a/website/docs/setup.mdx b/website/docs/setup.mdx index 7306af70..3df7f214 100644 --- a/website/docs/setup.mdx +++ b/website/docs/setup.mdx @@ -22,9 +22,13 @@ To configure iOS SDK integration you need to: - CDN will cache all translations in the release for up to 1 hour and even if new translations are released in Crowdin, CDN may return them with a delay. ::: +## Getting Started + +There are several ways to set up the SDK, depending on your project. Make sure you have completed the steps in the [Installation](installation) section before proceeding. + ### Swift -Open the *AppDelegate.swift* file and add: +Open the `AppDelegate.swift` file and add: ```swift import CrowdinSDK @@ -43,7 +47,7 @@ CrowdinSDK.startWithConfig(crowdinSDKConfig, completion: { ### Objective-C -In the *AppDelegate.m* add: +In the `AppDelegate.m` add: ```objectivec @import CrowdinSDK @@ -62,7 +66,7 @@ CrowdinProviderConfig *crowdinProviderConfig = [[CrowdinProviderConfig alloc] in CrowdinSDKConfig *config = [[[CrowdinSDKConfig config] withCrowdinProviderConfig:crowdinProviderConfig]]; [CrowdinSDK startWithConfig:config completion:^{ -// SDK is ready to use, put code to change language, etc. here + // SDK is ready to use, put code to change language, etc. here }]; ``` @@ -76,22 +80,51 @@ Add the following code to your Library Search Paths: $(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME) ``` -2. Add `use_frameworks!` to your Podfile. +2. Add `use_frameworks!` to your `Podfile`. -## Alternative Setup: Info.plist +### Alternative Setup: Info.plist -You can also configure basic SDK settings in Info.plist: +Configure basic SDK settings in your project's `Info.plist` file: 1. Add these keys to *Info.plist*: - `CrowdinDistributionHash` (String) - Your Crowdin CDN hash - `CrowdinSourceLanguage` (String) - Source language code in [ISO 639-1](http://www.loc.gov/standards/iso639-2/php/English_list.php) format -2. In AppDelegate call: +2. In your `AppDelegate` call the following method: - Swift: `CrowdinSDK.start()` - Objective-C: `[CrowdinSDK start]` :::caution -Using the `Info.plist` setup method, you cannot configure Screenshots and Real-Time Preview features. +The `Info.plist` configuration method does not support Screenshots and Real-Time Preview features. To use these features, configure the SDK programmatically. +::: + +## Config Options Reference + +The SDK configuration is done using the `CrowdinSDKConfig` class. The following options are available: + +| Option | Description | Example Value | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------|------------------------| +| `hashString` | Distribution Hash | `"7a0c1...o3b"` | +| `sourceLanguage` | Source language code ([ISO 639-1](http://www.loc.gov/standards/iso639-2/php/English_list.php)) | `sourceLanguage: "en"` | +| `organizationName` | Organization domain (Enterprise only) | `"mycompany"` | +| `settingsEnabled` | Enable [SDK Controls](/advanced-features/sdk-controls) | `true` | +| `accessToken` | Crowdin API Access Token. An alternative to the OAuth-based authorization in the Screenshots and Real-Time Preview features | `"your_token"` | + +### OAuth Options + +The `CrowdinLoginConfig` class provides OAuth configuration options: + +| Option | Description | Example Value | +|----------------|-----------------------------------------------------|--------------------| +| `clientId` | Crowdin OAuth Client ID | `"gpY2yT...x3TYB"` | +| `clientSecret` | Crowdin OAuth Client Secret | `"Xz95t...EDx9T"` | +| `scope` | OAuth scope (e.g., `project.screenshot`, `project`) | `"project"` | +| `redirectURI` | Custom URL scheme for your app | `"crowdintest://"` | + +The `CrowdinLoginConfig` configuration is required for the [Screenshots](/advanced-features/screenshots) and [Real-Time Preview](/advanced-features/real-time-preview) features only. + +:::info +Read more about creating an [OAuth application](https://support.crowdin.com/account-settings/#oauth) in Crowdin. ::: ## Additional Features @@ -114,16 +147,50 @@ By default, SDK searches for new translation once per application load, but not Where `interval` - defines translations update time interval in seconds. Minimum allowed interval is 15 minutes (900 seconds). -## Change locale programmatically +### Change locale programmatically By default, the SDK relies on the device locale. To change the SDK target language on the fly regardless of the device locale, use the following method: ```swift +import CrowdinSDK + CrowdinSDK.enableSDKLocalization(true, localization: "") ``` Where `` is the target language in [ISO 639-1](http://www.loc.gov/standards/iso639-2/php/English_list.php) format. +You can also use the `CrowdinSDK.currentLocalization` property to get or set the current localization language code used by the Crowdin SDK. When you set this property, the SDK triggers a localization download if needed: + +```swift +import CrowdinSDK + +// Set the current localization to German +CrowdinSDK.currentLocalization = "de" + +// ... + +// Get the current localization +if let currentLocale = CrowdinSDK.currentLocalization { + print("Current localization: \(currentLocale)") +} else { + print("Using default localization") +} +``` + +### `addDownloadHandler` closure + +The `addDownloadHandler` method allows you to add a closure that will be called every time new localization is downloaded. This can be useful for performing actions such as updating the user interface or processing the newly downloaded localization data: + +```swift +let handlerId = CrowdinSDK.addDownloadHandler { + print("New localization downloaded!") + // Perform additional actions, such as updating the UI +} + +// Optionally, you can remove the handler later if needed +CrowdinSDK.removeDownloadHandler(handlerId) +``` + ## SwiftUI Support SwiftUI support requires explicit localization calls. Use either: @@ -147,22 +214,3 @@ The Crowdin SDK supports the following localization file formats: - [iOS Strings](https://store.crowdin.com/strings) and [Stringsdict](https://store.crowdin.com/stringsdict) (`.strings`, `.stringsdict`) - [Apple XLIFF](https://store.crowdin.com/xliff) (`.xliff`) - [Apple Strings Catalog](https://store.crowdin.com/string_catalog) (`.xcstrings`). ⚠️ Only the CDN Content Delivery feature is available for the Apple Strings Catalog format. The Screenshots and Real-Time Preview features are not yet supported. - -## Config Options Reference - -| Option | Description | Example Value | -|--------------------|------------------------------------------------------------------------------------------------|------------------------| -| `hashString` | Distribution Hash | `"7a0c1...o3b"` | -| `sourceLanguage` | Source language code ([ISO 639-1](http://www.loc.gov/standards/iso639-2/php/English_list.php)) | `sourceLanguage: "en"` | -| `organizationName` | Organization domain (Enterprise only) | `"mycompany"` | -| `settingsEnabled` | Enable SDK Controls | `true` | -| `accessToken` | Crowdin API access token | `"your_token"` | - -### OAuth Options - -| Option | Description | Example Value | -|----------------|-----------------------------------------------------|--------------------| -| `clientId` | OAuth Client ID | `"gpY2yT...x3TYB"` | -| `clientSecret` | OAuth Client Secret | `"Xz95t...EDx9T"` | -| `scope` | OAuth scope (e.g., "project.screenshot", "project") | `"project"` | -| `redirectURI` | Custom URL scheme for your app | `"crowdintest://"` |