granula

i18n tool for angular.js applications

npm install granula
12 downloads in the last week
24 downloads in the last month

Build Status

Introduction

granula is a tool which helps with i18n of angular.js applications.

See an example on jsfiddle: http://jsfiddle.net/GRaAL/EasQP/1/

Dependencies:

  • angular.js (>=1.0.8)

How to use

Simple way (for small apps)

  1. Get latest build from github (https://raw.github.com/AlexeyGrishin/granula/master/build/angularjs/granula.js). Sorry, will add bower component soon :(
  2. In your application add granula to the module dependencies angular.module('app', ['granula'])
  3. In your HTML markup the text you'd like to translate with 'gr-key' attribute

    <p gr-key='exact-key'>Would you like to continue?</p><button gr-key>Yes</button>

    Note that value of 'gr-key' attribute is used as translation key. If value is not specified then text itself will be used ('Yes' in example above)

  4. Create json with translation for languages you need, like this.

     {
       "exact-key": "Хотите продолжить?",
       "Yes": "Да"
     }
    
  5. Put it into separate file OR directly onto the page in <script> tag

     <script type='granula/lang' src='ru.json' gr-lang='ru'></script>
     <!-- OR -->
     <script type='granula/lang' gr-lang='it'>
         <!-- your json -->
     </script>
    

    Note that script tag shall be inside tag marked with ng-app, otherwise angular will not process it (and granula as well).

Complex way (for big apps)

  1. Steps 1-3 from Simple Way
  2. ``npm install -g granula```
  3. Create file called Granulafile in your project root and fill it following way:

     {
       "src": "src/html",
       "out": "src/html/lang",
       "languages": "ru,it,ua,fr"
     }
    
  4. Run granula in the directory with Granulafile

  5. granula will process your HTMLs, collect all keys (even not defined explicitly) and prepare json files in 'out' directory for all provided languages.
  6. Then you may edit these files. On the next run granula will add new keys to the file and mark absent ones as deleted but will not delete anything.

Features

Simplified pluralization expressions

For tags marked with 'gr-key' granula automatically parses 'pluralization expressions' like the following ones:

  • {{n}} task(s) ==> 1 task / 2 tasks
    • any expression with () is considered as 'pluralization expression'
    • it automatically binds to the nearest angular expression to the left
  • There (is,are):> {{n}} task(s) ==> There is 1 task / There are 2 tasks
    • in case you provide :> after right parenthesis then it will be bound to the nearest angular expression to the right
  • Empty file(s):empty.length found. (It,They):empty.length will be deleted ==> Empty file found. It will be deleted / Empty files found. They will be deleted
    • if you'd like to pluralize text over expression not used in text then just provide it after :. Note: you cannot use complex angular expressions and filters here, just variable names.
  • It is good \(or not)
    • for non-pluralization expressions you may escape your parenthesis
  • У нас {{n}} кош(ка,ки,ек) ==> У нас 1 кошка / У нас 2 кошки / У нас 6 кошек
    • works with other languages as well. Just provide as many suffixes in parenthesis how many pluralization forms exists in the language

Translation of attributes

  1. You need to provide list of attributes in 'gr-attrs' attribute

     <input gr-attrs='placeholder,title' title='Enter your first name' placeholder='First name'/>
    
  2. Then, if you'd like to, you may provide exact key names with 'gr-key-{attr}' attribute. If you do not do it then attribute text will be used as key in translation.

     <input gr-attrs='placeholder,title' 
       title='Enter your first name' gr-key-title='first-name-title'
       placeholder='First name' gr-key-placeholder='first-name-placeholder'/>
    

Roadmap

  1. Collect keys from js files as well
  2. More documentation and examples
npm loves you