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.

Overview

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

1. System Screenshot Buttons: Utilize the default system buttons/gestures for taking screenshots
2. Custom Handler: Implement your own screenshot trigger (e.g., an in-app button or gesture, or an automated workflow)
3. SDK Controls Widget: Use the built-in SDK Controls UI widget for easy management

Setup

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

Kotlin

override fun onCreate() {
    super.onCreate()

    Crowdin.init(applicationContext,
        CrowdinConfig.Builder()
            .withDistributionHash(your_distribution_hash)
            .withScreenshotEnabled()
            .withSourceLanguage(source_language)
            .withAuthConfig(AuthConfig(
                client_id,
                client_secret,
                redirect_uri,
                request_auth_dialog
            ))
            .withOrganizationName(organization_name)   // required for Crowdin Enterprise
            .withNetworkType(network_type)             // optional
            .withUpdateInterval(interval_in_seconds)   // optional
            .build())
}

// Using system buttons to take screenshots and automatically upload them to Crowdin.
Crowdin.registerScreenShotContentObserver(this)

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    Crowdin.init(this,
        new CrowdinConfig.Builder()
            .withDistributionHash(your_distribution_hash)
            .withScreenshotEnabled()
            .withSourceLanguage(source_language)
            .withAuthConfig(new AuthConfig(
                client_id,
                client_secret,
                redirect_uri,
                request_auth_dialog
            ))
            .withOrganizationName(organization_name)   // required for Crowdin Enterprise
            .withNetworkType(network_type)             // optional
            .withUpdateInterval(interval_in_seconds)   // optional
            .build());
}

// Using system buttons to take screenshots and automatically upload them to Crowdin.
Crowdin.registerScreenShotContentObserver(this);

caution

• Ensure you've properly wrapped context for all activities where screenshots will be captured.
• Using the Crowdin.registerScreenShotContentObserver(this) (system button handler) to send screenshots to Crowdin requires storage permission for your application.

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 client_id and client_secret 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 ApiAuthConfig to pass the apiToken directly. This streamlined method is ideal for automated workflows, CI/CD pipelines, or scenarios where user interaction is not desired.

OAuth-based Authorization

Implements a secure web-based authorization flow using client_id and client_secret. This method:

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

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    Crowdin.authorize(this)
}

Java

@Override
public void onCreate(@Nullable Bundle savedInstanceState, @Nullable PersistableBundle persistentState) {
    super.onCreate(savedInstanceState, persistentState);
    Crowdin.authorize(this);
}

info

• To easily control the Screenshots feature you could also use the SDK Controls UI widget.

API Token Authorization

A streamlined approach using the ApiAuthConfig class that bypasses OAuth authentication. This method:

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

Kotlin

.withApiAuthConfig(
    ApiAuthConfig(
        apiToken = "your_crowdin_api_token",
    )
)

Java

.withApiAuthConfig(
    new ApiAuthConfig(
        "your_crowdin_api_token"
    )
)

Custom Screenshot Handler

Implement your own screenshot capture logic by setting up a custom handler. This provides complete control over the screenshot capture process and allows integration with your application's specific requirements.

Kotlin

Crowdin.sendScreenshot(activity!!, screenshotName, object : ScreenshotCallback {
    override fun onSuccess() {
        Log.d(TAG, "Screenshot uploaded")
    }

    override fun onFailure(throwable: Throwable) {
        Log.d(TAG, throwable.localizedMessage)
    }
})

Java

View.OnClickListener oclBtnOk = new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        Crowdin.sendScreenshot(YourActivity.this, screenshotName, new ScreenshotCallback() {
            @Override
            public void onSuccess() {
                Log.d("", "Screenshot uploaded");
            }

            @Override
            public void onFailure(Throwable throwable) {
                Log.d("", String.valueOf(throwable));
            }
      });
  }
};

Config Options

Config option	Description	Example
withDistributionHash	Distribution Hash	withDistributionHash("7a0c1...7uo3b")
withScreenshotEnabled	Enable Screenshots feature	withScreenshotEnabled()
withSourceLanguage	Source language code in your Crowdin project	withSourceLanguage("en")
withAuthConfig	Crowdin authorization config	withAuthConfig(AuthConfig(client_id, client_secret, redirect_uri, request_auth_dialog))
client_id, client_secret	Crowdin OAuth Client ID and Client Secret	"gpY2yC...cx3TYB", "Xz95tfedd0A...TabEDx9T"
redirect_uri	OAuth redirect URI (optional, defaults to "crowdintest://")	"your-custom://redirect" or "crowdintest://"
request_auth_dialog	Request authorization dialog	true (default) or false
withApiAuthConfig	Crowdin authorization API config	withApiAuthConfig(ApiAuthConfig(api_token))
api_token	Crowdin authorization token	"gpY2yC...cx3TYB"
withOrganizationName	An Organization domain name (for Crowdin Enterprise users only)	"mycompany" for Crowdin Enterprise or null for crowdin.com

tip

See the OAuth and API sections in your Crowdin account settings to obtain the necessary credentials.

Redirect URI Configuration

You can configure the OAuth redirect URI for authorization in two ways:

• Via AuthConfig (Recommended): Specify the redirect URI directly in your AuthConfig. This method provides more flexibility and doesn't require manifest configuration.
• Via App Scheme in Manifest: Configure the redirect URI using app scheme in your AndroidManifest.xml. When using this method, the redirect URL in your Crowdin OAuth app should be crowdintest://.

The OAuth App redirect URL should match your configured redirect URI:

• When using AuthConfig method: Set the redirect URL to match the redirect_uri parameter value (e.g., "your-custom://redirect")
• When using App scheme method: Set the redirect URL to match your app scheme (e.g., for scheme <data android:scheme="crowdintest" /> use crowdintest://)