[![Travis](https://img.shields.io/travis/locize/locizify/master.svg?style=flat-square)](https://travis-ci.org/locize/locizify) [![Coveralls](https://img.shields.io/coveralls/locize/locizify/master.svg?style=flat-square)](https://coveralls.io/github/locize/locizify) [![npm version](https://img.shields.io/npm/v/locizify.svg?style=flat-square)](https://www.npmjs.com/package/locizify) # locizify Drop the locizify script onto your website and it will automatically start to segment your content and connect it to your [locize](http://locize.com) project. Translating your content was never easier. Just drop the following line to your header to deliver your content in any language: ```html ``` Checkout this [video](https://youtu.be/f0ukRI0LMfo?t=180) to see locizify in action. locizify uses virtual-dom to update your page with translations based on the current content. MutationObserver is used to trigger translations on dynamically added content. So it should play well with any static or dynamic page not using a own virtual-dom implementation. locizify comes bundled with [i18next](http://i18next.com/). # Getting started ## Troubleshooting Make sure you set the `debug` option to `true`. This will maybe log more information in the developer console. **SaveMissing is not working** Did you wait 5-10 seconds before refreshing the locize UI? It may take a couple of seconds until the missing keys are sent and saved. Per default only `localhost` is allowed to send missing keys ([or update missing keys](https://www.i18next.com/overview/configuration-options#missing-keys)) (to avoid using this feature accidentally [in production](https://docs.locize.com/guides-tips-and-tricks/going-production)). If you're not using `localhost` during development you will have to set the `allowedAddOrUpdateHosts: ['your.domain.tld']`. If you use `saveMissing=true` via query paramenter, make sure you do **NOT** define the saveMissing option also in the script tag or via init option. ## Find more information locizify wraps some other modules from locize and i18next so there are additional valuable resources to read to get details on all the provided options: - i18next language detector: `?lng=de` --> [readme](https://github.com/i18next/i18next-browser-languageDetector) - locize backend --> [readme](https://github.com/locize/i18next-locize-backend) - i18next --> [website](https://www.i18next.com) Like always if not finding a solution of got a question - just ping us at support@locize.com. ## Adding locizify to your page Add the script to your page: ```html
... ``` 1. Reload your page. 2. Refresh your project on locize.io - there should be added a new namespace in your reference language having all the segments of this page. 3. Add a new language to your project and translate the content 4. Reload your page with `?lng='[newLanguage]'` 5. Reload your page in the locize incontext editor to directly translate on page. ## Initialize with optional options **IMPORTANT** make sure you do not add your apiKey in the production build to avoid misuse by strangers ### via attibutes on script element ```html ... ``` ### via init function ```html ... ``` ## Get project languages To build some dynamic language selector you can load the available languages: ```js locizify.getLanguages(function(err, lngs) { console.warn(lngs); }); // returns something like { "en": { "name": "English", "nativeName": "English", "translated": { "latest": 1, "production": 1 } }, "de": { "name": "German", "nativeName": "Deutsch", "translated": { "latest": 0.8, "production": 1 } } } ``` ## Delay initial translation ```js const translation = locizify.init({ autorun: false, }); setTimeout(function () { translation.start(); }, 1000); ``` ## Merge content / use html inside your translations Just set translated attribute: ```htmlall inside will be used as on segment, even if having other elements inside
// key = all inside will be used as on segment, even if having other elements inside ``` Same could be done using options: ```js mergeTags: [], // tags to merge innerHtml to one key inlineTags: [], // tags to inline (eg. a, span, abbr, ...) ignoreInlineOn: [], // tags to ignore inlining tags under inlineTags ``` ## Fragment replacement for links and images ```html ``` You will find `a.png` to be a key in your translation files - it's value can be replaced to eg. `a-de.png` for german (all other languages will fallback to `a.png`) ```html Open my statistics ``` `statistic` will be a regular key that can be translated. But be aware you will need to provide that routes - eg. using [localized routes on the server](https://github.com/i18next/i18next-express-middleware#add-localized-routes) ## Translating javascript code You can use the [i18next](https://i18next.com) instance used to provide the translation functionality directly. Just make sure the instance is initialized already: ```js ``` ## Avoid translating an element ###### By attribute Just set translated attribute: ```htmlfoo {{foo}}; foo2 {{foo2}}
plural {{count}} items
``` ## Set different namespaces Default would be translation. #### Set a different one: ```js locizify.init({ namespace: 'myNamespace', }); ``` #### autogenerate one per route: ```js locizify.init({ namespaceFromPath: true, }); ``` ## Access different namespaces This is useful for reused elements that are on every page, eg. like footer,... and you're using namespaceFromPath. This way you can avoid having that segments on every routes namespace file. ```js locizify.init({ namespaceFromPath: true ns: ['common'] // -> add additional namespaces to load }); ``` ```htmldifferent namespace common is used
all the way down