github.com/insionng/yougam@v0.0.0-20170714101924-2bc18d833463/libraries/Unknwon/i18n/README.md (about)

     1  i18n
     2  ====
     3  
     4  Package i18n is for app Internationalization and Localization.
     5  
     6  ## Introduction
     7  
     8  This package provides multiple-language options to improve user experience. Sites like [Go Walker](http://gowalker.org) and [gogs.io](http://gogs.io) are using this module to implement Chinese and English user interfaces.
     9  
    10  You can use following command to install this module:
    11  
    12      go get github.com/Unknwon/i18n
    13  
    14  ## Usage
    15  
    16  First of all, you have to import this package:
    17  
    18  ```go
    19  import "github.com/Unknwon/i18n"
    20  ```
    21  
    22  The format of locale files is very like INI format configuration file, which is basically key-value pairs. But this module has some improvements. Every language corresponding to a locale file, for example, under `conf/locale` folder of [gogsweb](https://github.com/gogits/gogsweb/tree/master/conf/locale), there are two files called `locale_en-US.ini` and `locale_zh-CN.ini`.
    23  
    24  The name and extensions of locale files can be anything, but we strongly recommend you to follow the style of gogsweb.
    25  
    26  ## Minimal example
    27  
    28  Here are two simplest locale file examples:
    29  
    30  File `locale_en-US.ini`:
    31  
    32  ```ini
    33  hi = hello, %s
    34  bye = goodbye
    35  ```
    36  
    37  File `locale_zh-CN.ini`:
    38  
    39  ```ini
    40  hi = 您好，%s
    41  bye = 再见
    42  ```
    43  
    44  ### Do Translation
    45  
    46  There are two ways to do translation depends on which way is the best fit for your application or framework.
    47  
    48  Directly use package function to translate:
    49  
    50  ```go
    51  i18n.Tr("en-US", "hi", "Unknwon")
    52  i18n.Tr("en-US", "bye")
    53  ```
    54  
    55  Or create a struct and embed it:
    56  
    57  ```go
    58  type MyController struct{
    59      // ...other fields
    60      i18n.Locale
    61  }
    62  
    63  //...
    64  
    65  func ... {
    66      c := &MyController{
    67          Locale: i18n.Locale{"en-US"},
    68      }
    69      _ = c.Tr("hi", "Unknwon")
    70      _ = c.Tr("bye")
    71  }
    72  ```
    73  
    74  Code above will produce correspondingly:
    75  
    76  - English `en-US`：`hello, Unknwon`, `goodbye`
    77  - Chinese `zh-CN`：`您好，Unknwon`, `再见`
    78  
    79  ## Section
    80  
    81  For different pages, one key may map to different values. Therefore, i18n module also uses the section feature of INI format configuration to achieve section.
    82  
    83  For example, the key name is `about`, and we want to show `About` in the home page and `About Us` in about page. Then you can do following:
    84  
    85  Content in locale file:
    86  
    87  ```ini
    88  about = About
    89  
    90  [about]
    91  about = About Us
    92  ```
    93  
    94  Get `about` in home page:
    95  
    96  ```go
    97  i18n.Tr("en-US", "about")
    98  ```
    99  
   100  Get `about` in about page:
   101  
   102  ```go
   103  i18n.Tr("en-US", "about.about")
   104  ```
   105  
   106  ### Ambiguity
   107  
   108  Because dot `.` is sign of section in both [INI parser](https://github.com/go-ini/ini) and locale files, so when your key name contains `.` will cause ambiguity. At this point, you just need to add one more `.` in front of the key.
   109  
   110  For example, the key name is `about.`, then we can use:
   111  
   112  ```go
   113  i18n.Tr("en-US", ".about.")
   114  ```
   115  
   116  to get expect result.
   117  
   118  ## Helper tool
   119  
   120  Module i18n provides a command line helper tool beei18n for simplify steps of your development. You can install it as follows:
   121  
   122  	go get github.com/Unknwon/i18n/ui18n
   123  
   124  ### Sync locale files
   125  
   126  Command `sync` allows you use a exist local file as the template to create or sync other locale files:
   127  
   128  	ui18n sync srouce_file.ini other1.ini other2.ini
   129  
   130  This command can operate 1 or more files in one command.
   131  
   132  ## More information
   133  
   134  If the key does not exist, then i18n will return the key string to caller. For instance, when key name is `hi` and it does not exist in locale file, simply return `hi` as output.