Latest 1.0.2
Homepage https://github.com/ianweng/STRLocalized
License MIT
Platforms ios 7.0, requires ARC
Authors

pod
license

STRLocalized is a powerful iOS library localization for changing language at runtime and localising strings with JSON files.

Screenshot 01

Change to a specific language

STRLocalized provides following 3 ways to change language with a specific language, among of them return YES if succeed, and return NO if fail.

Use json file

[STRLocalized useLanguage:@"zh"        // language code
                 resource:@"zh-Hans"]; // json file name without '.json'
Use NSDictionary

[STRLocalized useLanguage:@"en" // language code
                 resource:@{    // NSDictionary
                   @"Hello World!" : @"Hello World!",
                   @"Back" : @"Back",
                   @"System Language" : @"System Language"
                 }];
Use language packs

// 1st: set language packs
[STRLocalized setLanguagePacks:@{
  @"zh" : @"zh-Hans", // use json file
  @"en" : @{          // NSDictionary
    @"Hello World!" : @"Hello World!",
    @"Back" : @"Back",
    @"System Language" : @"System Language"
  },
  // can add more languages here
}];

// 2nd: change the language
[STRLocalized usePacksLanguage:@"en"];

Localise strings

After changing language, use NSLocalizedString(key, comment) to localise strings.

Notice language changed

When the app sets the language, STRLocalized sends a NSNotification named STRLocalized - languageChangedNotification. Use macro STRLocalized defined to add observers to update strings, like the example below:


@property(weak, nonatomic) IBOutlet UILabel *helloWorldLabel;
@property(nonatomic) BOOL reloadStringsNeeded;

- (instancetype)initWithCoder:(NSCoder *)aDecoder {
  self = [super initWithCoder:aDecoder];
  if (self) {
    // add language changed notification
    STRLOCALIZED_ADD_NOTIFICATION
  }
  return self;
}

// receive language changed notification
STRLOCALIZED_RECEIVE_NOTIFICATION(^{
  // set reload strings needed
  self.reloadStringsNeeded = YES;
});

- (void)viewWillAppear:(BOOL)animated {
  [super viewWillAppear:animated];

  // reload strings
  if (self.reloadStringsNeeded)
    [self.helloWorldLabel setText:NSLocalizedString(@"Hello World!", nil)];
}

- (void)dealloc {
  // remove language changed notification
  STRLOCALIZED_REMOVE_NOTIFICATION
}

Reload the previous language setting

When the app sets the language, the setting is recorded in NSUserDefaults, but the setting won’t be reloaded, if the app restarts. So if the app needs to load the previous setting when the app starts, can do:

When the app starts

// AppDelegate.m

[STRLocalized useSettingLanguageIfSet];
suggest to do

if (![STRLocalized useSettingLanguageIfSet]) { // return false, if fail
  // use a default language, if no language is set or previous setting is lost
  [STRLocalized useLanguage:@"zh" resource:@"zh-Hans"];
}

Follow the system language

If the app supports several languages and needs to follow the system language when the app starts, can do:

When the app starts

// AppDelegate.m

// 1st step: set language packs
[STRLocalized setLanguagePacks:@{
  @"zh" : @"zh-Hans",
  @"en" : @{
    @"Hello World!" : @"Hello World!",
    @"Back" : @"Back",
    @"System Language" : @"System Language"
  }
}];

// 2nd step: follow system language
[STRLocalized useSystemLanguageIfSupported];
suggest to do in 2nd step

if (![STRLocalized useSystemLanguageIfSupported]) { // return false, if fail
  // use a default language, if the system language is not supported
  [STRLocalized usePacksLanguage:@"en"];
}

Use language according to users’ behaviour (recommend)

If the app allows users to select the language (including following the system language or a specific languages) and needs to load language according to users’ behaviour when the app starts, can do:

When the app starts

// AppDelegate.m

[STRLocalized setLanguagePacks:@{
  @"zh" : @"zh-Hans",
  @"ja" : @"ja",
  @"ko" : @"ko",
  @"en" : @{
    @"Hello World!" : @"Hello World!",
    @"Back" : @"Back",
    @"System Language" : @"System Language"
  },
  @"es" : @"es",
  @"de" : @"de",
}];

if (![STRLocalized useLanguageByPriority]) {
  [STRLocalized usePacksLanguage:@"en"];
}
When users set to follow the system language

[STRLocalized
    setUsingLanguagePriority:STRLocalizedUsingLanguagePrioritySystem];
[STRLocalized useLanguageByPriority];
When users set a specific language

[STRLocalized
    setUsingLanguagePriority:STRLocalizedUsingLanguagePrioritySetting];
[STRLocalized usePacksLanguage:language];

By above, the app:

  • At first time start, try to follow the system language;
  • At first time start, use @"en" if the system language is not supported;
  • After first time starts, when it starts, if users didn’t set to follow the system language, use the previous language setting;
  • After first time starts, when it starts, if users set to follow the system language, try follow the system language;
  • After first time starts, when it starts, if users set to follow the system language and the system language is not supported, use the previous language setting.

Missing translations

STRLocalized overrides the localization method, so unfortunately the app has to provide translation for all system words, such as "Cancel", "Back" and so on. In order to quick check any missing translations, STRLocalized provides a block call-back.


[STRLocalized setLocalizedFailureBlock:^(NSString *str) {
  NSLog(@"%@", str);
}];

Installation

CocoaPods

  1. Add the following line in the project’s Podfile file:
    pod 'STRLocalized'.
  2. Run the command pod install from the Podfile folder directory.

STRLocalized has no dependencies over other pods.

License

The MIT License (MIT)

Copyright (c) 2016 Ian Weng | [email protected]

Latest podspec

{
    "name": "STRLocalized",
    "version": "1.0.2",
    "summary": "STRLocalized is a powerful iOS localization library for changing language at runtime and localising strings with JSON files.",
    "homepage": "https://github.com/ianweng/STRLocalized",
    "license": "MIT",
    "authors": {
        "Ian Weng": "[email protected]"
    },
    "source": {
        "git": "https://github.com/ianweng/STRLocalized.git",
        "branch": "master",
        "tag": "1.0.2"
    },
    "platforms": {
        "ios": "7.0"
    },
    "requires_arc": true,
    "source_files": "Classes/*"
}

Pin It on Pinterest

Share This