Permalink
Browse files

localization.md sample code guide WIP

  • Loading branch information...
1 parent 0b0273a commit 4584284584ec277cea92ab5f080e0e560a127a00 @groue committed Aug 20, 2012
Showing with 123 additions and 0 deletions.
  1. +123 −0 Guides/sample_code/localization.md
@@ -0,0 +1,123 @@
+[up](../../../../tree/master/Guides/sample_code), [next](../forking.md)
+
+Localization
+============
+
+We'll see how to localize portions of your templates, and eventually render the following template:
+
+ {{#localize}}
+ Hello {{name1}}, do you know {{name2}}?
+ {{/localize}}
+
+Into the various renderings below, depending on the current locale:
+
+ Hello Arthur, do you know Barbara ?
+ Bonjour Arthur, est-ce que tu connais Barbara ?
+ Hola Arthur, sabes Barbara?
+
+Yet this will be quite a smartish sample code, and it's better starting with more simple cases. We'll see how to localize:
+
+1. a section of a template
+
+ {{#localize}}Hello{{/localize}}
+
+2. a value
+
+ {{#localize}}{{greeting}}{{/localize}}
+
+3. a portion of a template *with arguments*, as above:
+
+ {{#localize}}Hello {{name1}}, do you know {{name2}}?{{/localize}}
+
+Of course, we'll always eventually use the standard `NSLocalizedString` function.
+
+Localizing a template section
+-----------------------------
+
+Let's localize the following template:
+
+ {{#localize}}Hello{{/localize}}
+
+And render, depending on the current locale:
+
+ Hello
+ Bonjour
+ Hola
+
+Mustache and GRMustache have no built-in localization feature. It is thus a matter of injecting our own application code into the template rendering, some code that localize its input.
+
+[Mustache lambda sections](../helpers.md) are our vector. We render them by attaching to a section an object that conforms to the `GRMustacheHelper` protocol. This object will execute the localization task.
+
+Let's use the `[GRMustacheHelper helperWithBlock:]` method, and the `innerTemplateString` property of the section object that the helper is given:
+
+ ```objc
+ // A template with a `localize` section:
+ NSString *templateString = @"{{#localize}}Hello{{/localize}}";
+
+ // A helper that returns the localized version of the inner template string
+ // of a section:
+ id localizeHelper = [GRMustacheHelper helperWithBlock:^(GRMustacheSection *section) {
+ return NSLocalizedString(section.innerTemplateString, nil);
+ }];
+
+ // A dictionary that attaches the helper to the `localize` key:
+ id data = @{ @"localize": localizeHelper };
+
+ // Render "Bonjour" for the French locale
+ NSString *rendering = [GRMustacheTemplate renderObject:data
+ fromString:templateString
+ error:NULL];
+ ```
+
+`GRMustacheHelper` and `innerTemplateString` are documented in the [helpers.md](../helpers.md) guide.
+
+
+Localizing a value
+------------------
+
+Template:
+
+ {{#localize}}{{greeting}}{{/localize}}
+
+Data:
+
+ { greeting: "Hello" }
+
+Rendering:
+
+ Hello
+ Bonjour
+ Hola
+
+Here we are not localizing a raw portion of the template. Instead, we are localizing a value that comes from the rendered data.
+
+Fortunately, GRMustacheSection objects are able to provide the helper with the rendering of their inner content: `Hello` in our case:
+
+ ```objc
+ // A template with a `localize` section:
+ NSString *templateString = @"{{#localize}}{{greeting}}{{/localize}}";
+
+ // A helper that returns the localized version of the section's rendering:
+ id localizeHelper = [GRMustacheHelper helperWithBlock:^(GRMustacheSection *section) {
+ // [section render] would return "Hello",
+ // the rendering of "{{greeting}}".
+ return NSLocalizedString([section render], nil);
+ }];
+
+ // A dictionary that attaches the helper to the `localize` key, and "Hello"
+ // to the `greeting` key:
+ id data = @{
+ @"greeting": @"Hello",
+ @"localize": localizeHelper
+ };
+
+ // Render "Bonjour" for the French locale
+ NSString *rendering = [GRMustacheTemplate renderObject:data
+ fromString:templateString
+ error:NULL];
+ ```
+
+`GRMustacheHelper` and `[GRMustacheSection render]` are documented in the [helpers.md](../helpers.md) guide.
+
+
+[up](../../../../tree/master/Guides/sample_code), [next](../forking.md)

0 comments on commit 4584284

Please sign in to comment.