• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    公众号

crowdin/mobile-sdk-android: Crowdin Android SDK delivers all new translations fr ...

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称(OpenSource Name):

crowdin/mobile-sdk-android

开源软件地址(OpenSource Url):

https://github.com/crowdin/mobile-sdk-android

开源编程语言(OpenSource Language):

Kotlin 100.0%

开源软件介绍(OpenSource Introduction):

Crowdin Android SDK

Crowdin Android SDK delivers all new translations from Crowdin project to the application immediately. So there is no need to update this application via Google Play Store to get the new version with the localization.

The SDK provides:

  • Over-The-Air Content Delivery – the localized content can be sent to the application from the project whenever needed.
  • Real-Time Preview – all the translations that are done in the Editor can be shown in your version of the application in real-time. View the translations already made and the ones you're currently typing in.
  • Screenshots – all the screenshots made in the application may be automatically sent to your Crowdin project with tagged source strings.

Downloads GitHub Release Date GitHub contributors GitHub

Azure DevOps builds (branch) Azure DevOps tests (branch) codecov

Table of Contents

Requirements

  • Android SDK version 16+

Installation

You have two ways to install Crowdin Android SDK.

  • From Jitpack

    Add this to your root build.gradle at the end of repositories:

    allprojects {
        repositories {
            ...
            maven { url 'https://jitpack.io' }
        }
    }

    Add the dependency:

    dependencies {
        implementation 'com.github.crowdin.mobile-sdk-android:sdk:1.5.3'
    }

    For Android project which already have transitive dependency of com.google.code.gson, after integration of Crowdin SDK, it will show you the following error during build time:

    Duplicate class com.google.gson.DefaultDateTypeAdapter found in modules xxx.jar (xxx.jar) and jetified-gson-2.8.5.jar (com.google.code.gson:gson:2.8.5)

    To resolve, either exclude gson from Crowdin or from your library is OK, but be sure to keep the newer one for backward-compatibility.

    implementation ('com.github.crowdin.mobile-sdk-android:sdk:1.5.3') {
        exclude group: 'com.google.code.gson', module: 'gson'
    }
  • Manually download or clone this module.

Setup

To configure Android SDK integration you need to:

  • Upload your xml localization files to Crowdin. If you have ready translations, you can also upload them.
  • Set up Distribution in Crowdin.
  • Set up SDK and enable Over-The-Air Content Delivery feature in your project.

Distribution is a CDN vault that mirrors the translated content of your project and is required for integration with Android app.

To manage distributions open the needed project and go to Over-The-Air Content Delivery. You can create as many distributions as you need and choose different files for each. You’ll need to click the Release button next to the necessary distribution every time you want to send new translations to the app.

Notes:

  • By default, the translation downloading happens asynchronously after launching the app. The downloaded translations will be used after the next launch of the app or Activity re-render. Otherwise, the previously cached translations will be used (or local translations if a cache does not exist). To enable the synchronous mode please see the Notes #9
  • The CDN feature does not update the localization files. if you want to add new translations to the localization files you need to do it yourself.
  • Once SDK receives the translations, it's stored on the device as application files for further sessions to minimize requests the next time the app starts. Storage time can be configured using withUpdateInterval option.
  • CDN caches all the translation in release for up to 15 minutes and even when new translations are released in Crowdin, CDN may return it with a delay.

To integrate SDK with your application you need to follow step by step instructions:

  1. Inject Crowdin translations by adding override method in BaseActivity class to inject Crowdin translations into the Context. If you already migrated to AppCompat 1.2.0+ version. Please use this method:

    Kotlin
    override fun getDelegate() = BaseContextWrappingDelegate(super.getDelegate())
    Java
    @NonNull
    @Override
    public AppCompatDelegate getDelegate() {
        return new BaseContextWrappingDelegate(super.getDelegate());
    }

    And for AppCompat 1.1.0 and lower use this:

    Kotlin
    override fun attachBaseContext(newBase: Context) {
        super.attachBaseContext(Crowdin.wrapContext(newBase))
    }
    Java
    @Override
    protected void attachBaseContext(Context newBase) {
        super.attachBaseContext(Crowdin.wrapContext(newBase));
    }

    Note! If you don’t have BaseActivity class add the following code to all of your activities.

  2. Enable Over-The-Air Content Delivery in your project so that application can pull translations from CDN vault. Add the following code to App/Application class:

    Kotlin
    override fun onCreate() {
        super.onCreate()
    
        Crowdin.init(applicationContext,
            CrowdinConfig.Builder()
                .withDistributionHash(your_distribution_hash)
                .withNetworkType(network_type)                // optional
                .withUpdateInterval(interval_in_seconds)      // optional
                .build())
    }
    Java
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
    
        Crowdin.init(this,
            new CrowdinConfig.Builder()
                .withDistributionHash(your_distribution_hash)
                .withNetworkType(network_type)                // optional
                .withUpdateInterval(interval_in_seconds)      // optional
                .build());
    }
    Config option Description Example
    withDistributionHash Distribution Hash withDistributionHash("7a0c1...7uo3b")
    withNetworkType Network type to be used for translations download Acceptable values are:
    - NetworkType.ALL (default)
    - NetworkType.CELLULAR
    - NetworkType.WIFI
    withUpdateInterval Translations update interval in seconds. The minimum and the default value is 15 minutes. Translations will be updated every defined time interval once per application load withUpdateInterval(900)

Advanced Features

Real-time Preview

All the translations that are done in the Editor can be shown in your version of the application in real-time. View the translations already made and the ones you're currently typing in.

  1. Add the following code to the Application class:

    Kotlin
    override fun onCreate() {
        super.onCreate()
    
        Crowdin.init(applicationContext,
            CrowdinConfig.Builder()
                .withDistributionHash(your_distribution_hash)
                .withRealTimeUpdates()
                .withSourceLanguage(source_language)
                .withAuthConfig(AuthConfig(client_id, client_secret, organization_name, request_auth_dialog))
                .withNetworkType(network_type)                                           // optional
                .withUpdateInterval(interval_in_seconds)                                 // optional
                .build())
    }
    Java
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
    
        Crowdin.init(this,
            new CrowdinConfig.Builder()
                .withDistributionHash(your_distribution_hash)
                .withRealTimeUpdates()
                .withSourceLanguage(source_language)
                .withAuthConfig(new AuthConfig(client_id, client_secret, organization_name, request_auth_dialog))
                .withNetworkType(network_type)                                           // optional
                .withUpdateInterval(interval_in_seconds)                                 // optional
                .build());
    }
    Config option Description Example
    withDistributionHash Distribution Hash withDistributionHash("7a0c1...7uo3b")
    withRealTimeUpdates Enable Real-Time Preview feature withRealTimeUpdates()
    withSourceLanguage Source language code in your Crowdin project withSourceLanguage("en")
    withAuthConfig Crowdin authorization config withAuthConfig(AuthConfig("client_id", "client_secret", "organization_name"))
    client_id, client_secret Crowdin OAuth Client ID and Client Secret "gpY2yC...cx3TYB", "Xz95tfedd0A...TabEDx9T"
    organization_name An Organization domain name
    ℹ️ for Crowdin Enterprise users only
    "mycompany" for Crowdin Enterprise or null for crowdin.com
    request_auth_dialog Request authorization dialog true by default or false
    withNetworkType Network type to be used for translations download Acceptable values are:
    - NetworkType.ALL (default)
    - NetworkType.CELLULAR
    - NetworkType.WIFI
    withUpdateInterval Translations update interval in seconds. The minimum and the default value is 15 minutes. Translations will be updated every defined time interval once per application load withUpdateInterval(900)
  2. Crowdin Authorization is required for Real-Time Preview feature. Create connection using Activity/Fragment method inMainActivity class:

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

    You can disconnect via:

    override fun onDestroy() {
        super.onDestroy()
        // Close connection with Crowdin.
        Crowdin.disconnectRealTimeUpdates()
    }
  3. To use this feature you also need to wrap context for your activities. See Setup.

  4. OAuth redirect URL should match your App scheme. For example, for scheme <data android:scheme="crowdintest" /> redirect URL in Crowdin should be crowdintest://

  5. To easily control the Real-Time Preview feature you could also use the SDK Controls UI widget.

Screenshots

Enable if you want all the screenshots made in the application to be automatically sent to your Crowdin project with tagged strings. This will provide additional context for translators.

You can take screenshots and automatically upload them tagged to Crowdin in the following ways:

  • using the system buttons for taking a screenshot
  • create your own handler (for example, clicking on some button in your application)
  • using the SDK Controls UI widget.

To enable the Screenshots feature follow these instructions:

  1. Add the following code to the 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, organization_name, request_auth_dialog))
                .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, organization_name, request_auth_dialog))
               .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);
    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", "organization_name"))
    client_id, client_secret Crowdin OAuth Client ID and Client Secret "gpY2yC...cx3TYB", "Xz95tfedd0A...TabEDx9T"
    organization_name An Organization domain name
    ℹ️ for Crowdin Enterprise users only
    "mycompany" for Crowdin Enterprise or null for crowdin.com
    request_auth_dialog Request authorization dialog true by default or false
    withNetworkType Network type to be used for translations download Acceptable values are:
    - NetworkType.ALL (default)
    - NetworkType.CELLULAR
    - NetworkType.WIFI
    withUpdateInterval Translations update interval in seconds. The minimum and the default value is 15 minutes. Translations will be updated every defined time interval once per application load withUpdateInterval(900)

    Note! Using Crowdin.registerScreenShotContentObserver(this) (system buttons handler) for sending screenshots to Crowdin requires Storage permission for your app.

  2. Crowdin Authorization is required for Screenshots feature. Create connection using Activity/Fragment method in MainActivity class:

    Kotlin
    override fun onCreate(savedInstanceState: Bundle?) {
        Crowdin.authorize(activity)
    }
    Java
    @Override
    public void onCreate(@Nullable Bundle savedInstanceState, @Nullable PersistableBundle persistentState) {
        super.onCreate(savedInstanceState, persistentState);
        Crowdin.authorize(this);
    }
  3. If you want to setup own handler for capturing screenshots you can do it programmatically with callback:

    Kotlin
    Crowdin.sendScreenshot(activity!!, 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, new ScreenshotCallback() {
                @Override
                public void onSuccess() {
                    Log.d("", "Screenshot uploaded");
                }
    
                @Override
                public void onFailure(Throwable throwable) {
                    Log.d("", String.valueOf(throwable));
                }
           });
       }
    };
  4. To use this feature you also need to wrap context for your activities. See Setup.

  5. OAuth redirect URL should match your App scheme. For example, for scheme <data android:scheme="crowdintest" /> redirect URL in Crowdin should be crowdintest://

File Export Patterns

You can set file export patterns and check existing ones using File Settings. The following placeholders are supported:

Name Description
%language% Language name (e.g. Ukrainian)
%two_letters_code% Language code ISO 639-1 (e.g. uk)
%three_letters_code% Language code ISO 639-2/T (e.g. ukr)
%locale% Locale (e.g. uk-UA)
%locale_with_underscore% Locale (e.g. uk_UA)
%android_code% Android Locale identifier used to name "values-" directories

Notes

  1. Crowdin works with current locale, if you change locale programmatically use the language plus country format:

    Locale("en", "US")

    Example of language change in App.kt:

    /**
     * Should be overridden in case you want to change locale programmatically.
     * For custom language set your application locale taking into account constraints for language and country/region
     * This should match with `Locale code:` for your custom language on Crowdin platform.
     *
     * language - [a-zA-Z]{2,8}
     * country/region - [a-zA-Z]{2} | [0-9]{3}
     *
     * Example: "aa-BB"
     * */
    override fun attachBaseContext(newBase: Context) {
        languagePreferences = LanguagePreferences(newBase)
        super.attachBaseContext(ContextWrapper(newBase.updateLocale(languagePreferences.getLanguageCode())))
    }
  2. For displaying a string, Crowdin tries to find that in dynamic strings, and will use bundled version as fallback. In the other words, Only the new provided strings will be overridden and for the rest the bundled version will be used.

  3. To translate menu items you need to update your onCreateOptionsMenu method:

    override fun onCreateOptionsMenu(menu: Menu): Boolean {
        menuInflater.inflateWithCrowdin(R.menu.activity_menu, menu, resources)
        return true
    }
    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
        ExtentionsKt.inflateWithCrowdin(getMenuInflater(), R.menu.your_menu, menu, getResources());
        return true;
    }
  4. In case you have custom views that uses TypedArray and stylable attributes, you will need to use such approach:

    val textId = typedArray.getResourceId(R.styleable.sample_item, 0)
    textView.setText(textId)

    instead of typedArray.getString(R.styleable.sample_item)

  5. Activity title defined via AndroidManifest won't be translated.

    <activity
        android:name=".activities.SampleActivity"
        android:label="@string/title"/>

    You can simply update your toolbar inside of activity or fragment:

    toolbar.setTitle(R.string.title);
  6. In case your project already overrides attachBaseContext:

    super.attachBaseContext(Crowdin.wrapContext(SomeLib.wrap(newBase)));
  7. You can register/unregister observer for data changes by adding this lines:

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

    It has callback method onDataChanged() that can be used to invalidate your UI (TextView/Menu etc). It will use downloaded resources automatically.

    override fun onDataChanged() {
        invalidateOptionsMenu()
        Crowdin.updateMenuItemsText(R.menu.activity_main_drawer, navigationView.menu, resources)
        toolbarMain.title = getString(R.string.category)
    }

    Otherwise new resources will be applied on activity restart.

  8. ShakeDetector for triggering force upload from Crowdin. It will try to download latest updates from release.

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

    On each shake event it will trigger Crowdin.forceUpdate(this) method. You can call this method from your app. Also, there are other public methods in Crowdin class. You can find details in kotlin doc files.

  9. Synchronous mode. You can trigger force upload from Crowdin while launching Splash Activity and after that open Main Activity

    override fun onCreate(savedInstanceState: Bundle?) {
        Crowdin.forceUpdate(this) {
            startActivity(Intent(this, MainActivity::class.java))
            finish()
        }
    }
  10. In case you have custom TextView with string specified in xml make sure you follow this naming convention PlaceholderTextView otherwise SDK will skip this view during inflating process and it won't be translated.

Limitations

  1. Plurals are supported from Android SDK version 24.
  2. TabItem text added via xml won't be updated. There is workaround: you can store tabItem titles in your string-array and add tabs dynamically.
  3. PreferenceScreen defined via XML not supported.

Contributing

If you want to contribute please read the Contributing guidelines.

Seeking Assistance

If you find any problems or would like to suggest a feature, please feel free to file an issue on Github at Issues Page.

Need help working with Crowdin Android SDK or have any questions? Contact Customer Success Service.

Security

Crowdin Android SDK CDN feature is built with security in mind, which means minimal access possible from the end-user is required. When you decide to use Crowdin Android SDK, please make sure you’ve made the following information accessible to your end-users.

  • We use the advantages of Amazon Web Services (AWS) for our computing infrastructure. AWS has ISO 27001 certification and has completed multiple SSAE 16 audits. All the translations are stored at AWS servers.
  • When you use Crowdin Android SDK CDN – translations are uploaded to Amazon CloudFront to be delivered t

鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap