Skip to content

Localization on iOS

iOS uses the system default behavior for localizing user experience. To enable supported language, your application must provide that localization too. Otherwise, the localization will fall back to English.

Changing Localization

To change existing localization, you can utilize the localization hook localizationHandler provided by the Document Reader SDK. This closure is called every time a string is requested.

To see all the localization keys, look up the RegulaSDK.strings file at DocumentReader.xcframework/ios-arm64/DocumentReader.framework/en.lproj/RegulaSDK.strings.

Here is an example of how you can add your own CustomLocalization.strings file and override any existing localization provided by the Document Reader SDK:

DocReader.shared.localizationHandler = { localizationKey in
    // This will look up localization in `CustomLocalization.strings`.
    let result = NSLocalizedString(localizationKey, tableName: "CustomLocalization", comment: "")

    // Localization found in CustomLocalization.
    if result != localizationKey {
        return result
    }

    // By returning nil we fallback to the default localization provided by SDK.
    return nil
}

RGLDocReader.shared.localizationHandler = ^NSString * _Nullable(NSString * _Nonnull localizationKey) {
  // This will look up localization in `CustomLocalization.strings`.
  NSString *result = NSLocalizedStringFromTable(localizationKey, @"CustomLocalization", "");

  // Localization found in CustomLocalization.
  if (![result isEqualToString:localizationKey]) {
    return result;
  }

  // By returning nil we fallback to the default localization provided by SDK.
  return nil;
};

Danger

Avoid changing the iOS system language (by using the AppleLanguages pref key) from within your application. This goes against the basic iOS user model for switching languages in the Settings app and uses a preference key that is not documented. At some point in the future, the key name may change and that would break your application.

You can have a look at the example of how we did implement this in our app that is available on App Store: Menu -> Settings -> Advanced -> Language.

Additional information

For more information on localizing your application and best practices, please see the official Apple documentation.

Next Steps