Screenshots

The Screenshots feature enhances the localization workflow by automatically capturing and uploading tagged screenshots from your application to your Crowdin project. This provides translators with valuable visual context, ensuring more accurate and contextually appropriate translations.

caution

The Screenshots feature is intended for development and staging environments only. Enabling this feature in production builds could expose sensitive UI information and impact app performance. For production releases, ensure the Screenshots feature is disabled to maintain security and optimal performance.

Overview

You can capture and upload tagged screenshots to Crowdin in two ways:

1. SDK Controls Widget: Use the built-in SDK Controls UI widget for easy management
2. Custom Handler: Implement your own screenshot trigger (e.g., an in-app button or gesture, or an automated workflow)

Setup

Swift

To enable the Screenshots feature in your application, add the following configuration to your Podfile:

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

Authorization

The Screenshots feature requires authorization to transmit screenshots to your Crowdin project. Choose from two authorization methods based on your needs:

• OAuth-based Authorization: Uses clientId and clientSecret for web-based authorization. This method implements a secure OAuth flow that opens a dialog for users to authorize the application. Best suited for development environments and when user interaction is acceptable.
• API Token Authorization: Uses the accessToken to pass the API Personal Access Token directly. This streamlined method is ideal for automated workflows, CI/CD pipelines, or scenarios where user interaction is not desired.

If both methods are configured, access token authentication takes priority.

OAuth-based Authorization

Implements a secure web-based authorization flow using clientId and clientSecret. This method:

• Opens a dialog for user authorization
• Provides a secure authentication process
• Is ideal for development and testing environments

To enable OAuth-based authorization, add the following configuration to your AppDelegate class:

Swift

AppDelegate.swift

let crowdinProviderConfig = CrowdinProviderConfig(hashString: "{your_distribution_hash}",
    sourceLanguage: "{source_language}",
    organizationName: "{organization_name}") // Optional. Required for Enterprise only

var loginConfig: CrowdinLoginConfig
do {
   loginConfig = try CrowdinLoginConfig(clientId: "{client_id}",
       clientSecret: "{client_secret}",
       scope: "project.screenshot",
       redirectURI: "{redirectURI}")
} catch {
    print(error)
    // CrowdinLoginConfig initialization error handling
}

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
})

Objective-C

CrowdinProviderConfig *crowdinProviderConfig = [[CrowdinProviderConfig alloc] initWithHashString:@"" sourceLanguage:@"" organizationName:@"{organization_name}"];

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

if (!error) {
    CrowdinSDKConfig *config = [[[[CrowdinSDKConfig config]
        withCrowdinProviderConfig:crowdinProviderConfig]
        withScreenshotsEnabled:YES]
        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
}

For OAuth authentication, you need to handle authorization callback in your application:

Swift

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

Objective-C

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

If you are using SceneDelegate, you need to handle callback in the SceneDelegate class implement method:

Swift

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

Objective-C

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

API Token Authorization

A streamlined approach using the accessToken option that bypasses OAuth authentication. This method:

• Allows direct API token integration
• Requires no user interaction
• Is perfect for CI/CD pipelines and automated workflows

Swift

AppDelegate.swift

let crowdinProviderConfig = CrowdinProviderConfig(hashString: "{your_distribution_hash}",
    sourceLanguage: "{source_language}",
    organizationName: "{organization_name}") // Optional. Required for Enterprise only

let crowdinSDKConfig = CrowdinSDKConfig.config()
    .with(crowdinProviderConfig: crowdinProviderConfig)
    .with(screenshotsEnabled: true)
    .with(accessToken: "your_access_token")
    .with(settingsEnabled: true)

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

Objective-C

CrowdinProviderConfig *crowdinProviderConfig = [[CrowdinProviderConfig alloc] initWithHashString:@"" sourceLanguage:@"" organizationName:@"{organization_name}"];

CrowdinSDKConfig *config = [[[[CrowdinSDKConfig config]
    withCrowdinProviderConfig:crowdinProviderConfig]
    withScreenshotsEnabled:YES]
    withAccessToken:@"your_access_token"];

Custom Screenshot Handler

You can use one of two methods to take screenshots programmatically:

1. Basic screenshot capture:

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

2. Capture and update existing screenshot:

   
   CrowdinSDK.captureAndUpdateScreenshot(name: "{screenshot_name}") { result in
       switch result {
           case .new: print("New screenshot captured")
           case .udpated: print("Screenshot updated")
       }
   } errorHandler: { error in
       print("Error: \(error)")
   }

The captureAndUpdateScreenshot method is useful when you want to update an existing screenshot in your Crowdin project. This can help maintain screenshot organization by updating existing screenshots rather than creating new ones each time.

You can also capture screenshots of specific UIView instances with either method.

Config Options Reference

Option	Description	Required	Example Value
hashString	Distribution Hash	Yes	"7a0c1...o3b"
sourceLanguage	Source language code (ISO 639-1)	Yes	sourceLanguage: "en"
organizationName	Organization domain (Enterprise only)	No	"mycompany"
settingsEnabled	Enable SDK Controls	No	true
screenshotsEnabled	Enable Screenshots 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
clientId	OAuth Client ID	Yes*	"gpY2yT...x3TYB"
clientSecret	OAuth Client Secret	Yes*	"Xz95t...EDx9T"
scope	OAuth scope (must include "project.screenshot")	Yes*	"project.screenshot"
redirectURI	Custom URL scheme for your app	No	"crowdintest://"

• Required only if using OAuth authentication instead of access token.

Troubleshooting

If you get the error:

Error while capturing screenshot - The operation couldn't be completed. (There are no localized strings detected on current screen. error 99999.)

Make sure that your current locale matches your project's source (default) language.