Skip to content

Commit

Permalink
docs: various improvements and clarifications (#313)
Browse files Browse the repository at this point in the history
  • Loading branch information
@andrii-bodnar
andrii-bodnar authored Feb 6, 2025
1 parent 19c7e6d commit 132607b
Show file tree
Hide file tree
Showing 7 changed files with 109 additions and 46 deletions.
13 changes: 11 additions & 2 deletions website/docs/advanced-features/real-time-preview.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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!
Expand Down Expand Up @@ -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"` |
Expand All @@ -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.
:::
10 changes: 8 additions & 2 deletions website/docs/advanced-features/screenshots.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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!
Expand Down Expand Up @@ -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"` |

Expand All @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion website/docs/advanced-features/sdk-controls.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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!
Expand Down
4 changes: 2 additions & 2 deletions website/docs/example.md
View file
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion website/docs/guides/screenshots-automation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 10 additions & 10 deletions website/docs/installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand All @@ -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'
Expand All @@ -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|
Expand All @@ -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`
Expand All @@ -77,15 +77,15 @@ 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")
]
```

:::tip
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"))
```
:::

Expand All @@ -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.
:::

Expand Down
104 changes: 76 additions & 28 deletions website/docs/setup.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -43,7 +47,7 @@ CrowdinSDK.startWithConfig(crowdinSDKConfig, completion: {

### Objective-C

In the *AppDelegate.m* add:
In the `AppDelegate.m` add:

```objectivec
@import CrowdinSDK
Expand All @@ -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
}];
```
Expand All @@ -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
Expand All @@ -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: "<language_code>")
```

Where `<language_code>` 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:
Expand All @@ -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://"` |

0 comments on commit 132607b

Please sign in to comment.