From 22ae8d5073c414f19ca0a191c70e952e4c736547 Mon Sep 17 00:00:00 2001 From: Sylvain Date: Tue, 3 Dec 2019 17:15:32 +0100 Subject: [PATCH] updated and refactored readme updated instructions to setup a development environment splitted readme into multiple files to improve clarity --- CHANGELOG.md | 1 + README.md | 308 +----------------- doc/development_readme.md | 231 +++++++++++++ .../README.md => doc/docker-compose_readme.md | 0 doc/translation_readme.md | 75 +++++ 5 files changed, 319 insertions(+), 296 deletions(-) create mode 100644 doc/development_readme.md rename docker/README.md => doc/docker-compose_readme.md (100%) create mode 100644 doc/translation_readme.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 58b56bddb..b5271df47 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ - Updated moment-timezone - Added freeCAD files as default allowed extensions - Rake task to sync local users with Stripe +- Updated and refactored README - Fix a bug: unable to remove the picture from a training - Fix a bug: no alerts on errors during admin creation - Fix a bug: replaces all Time.now by DateTime.current to prevent time zones issues [Taiga#134] diff --git a/README.md b/README.md index 458c69baf..9948f4245 100644 --- a/README.md +++ b/README.md @@ -10,26 +10,13 @@ FabManager is the Fab Lab management solution. It provides a comprehensive, web- 1. [Software stack](#software-stack) 2. [Contributing](#contributing) 3. [Setup a production environment](#setup-a-production-environment) -4. [Setup a development environment](#setup-a-development-environment)
-4.1. [General Guidelines](#general-guidelines)
-5. [PostgreSQL](#postgresql)
-5.1. [Install PostgreSQL 9.6](#setup-postgresql) -6. [ElasticSearch](#elasticsearch)
-6.1. [Install ElasticSearch](#setup-elasticsearch)
-6.2. [Rebuild statistics](#rebuild-stats)
-6.3. [Backup and Restore](#backup-and-restore-elasticsearch) -7. [Internationalization (i18n)](#i18n)
-7.1. [Translation](#i18n-translation)
-7.1.1. [Front-end translations](#i18n-translation-front)
-7.1.2. [Back-end translations](#i18n-translation-back)
-7.2. [Configuration](#i18n-configuration)
-7.2.1. [Settings](#i18n-settings)
-7.2.2. [Applying changes](#i18n-apply) -8. [Open Projects](#open-projects) -9. [Plugins](#plugins) -10. [Single Sign-On](#sso) -11. [Known issues](#known-issues) -12. [Related Documentation](#related-documentation) +4. [Setup a development environment](#setup-a-development-environment) +5. [Internationalization (i18n)](#i18n) +6. [Open Projects](#open-projects) +7. [Plugins](#plugins) +8. [Single Sign-On](#sso) +9. [Known issues](#known-issues) +10. [Related Documentation](#related-documentation) @@ -54,293 +41,22 @@ Contributions are welcome. Please read [the contribution guidelines](CONTRIBUTIN ## Setup a production environment To run fab-manager as a production application, this is highly recommended to use [Docker-compose](https://docs.docker.com/compose/overview/). -The procedure to follow is described in the [docker-compose readme](docker/README.md). +The procedure to follow is described in the [docker-compose readme](doc/docker-compose_readme.md). ## Setup a development environment -In you intend to run fab-manager on your local machine to contribute to the project development, you can set it up with the following procedure. +In you intend to run fab-manager on your local machine to contribute to the project development, you can set it up by following the [development readme](doc/development_readme.md). +This procedure relies on docker to set-up the dependencies. -This procedure is not easy to follow so if you don't need to write some code for Fab-manager, please prefer the [docker-compose installation method](docker/README.md). - -Optionally, you can use a virtual development environment that relies on Vagrant and Virtual Box by following the [virtual machine instructions](doc/virtual-machine.md). - - -### General Guidelines - -1. Install RVM, with the ruby version specified in the [.ruby-version file](.ruby-version). - For more details about the process, please read the [official RVM documentation](http://rvm.io/rvm/install). - If you're using ArchLinux, you may have to [read this](doc/archlinux_readme.md) before. - -2. Install NVM, with the node.js version specified in the [.nvmrc file](.nvmrc). - For instructions about installing NVM, please refer to [the NVM readme](https://github.com/creationix/nvm#installation). - -3. Install Yarn, the front-end package manager. - Depending on your system, the installation process may differ, please read the [official Yarn documentation](https://yarnpkg.com/en/docs/install#debian-stable). - -4. Install docker. - Your system may provide a pre-packaged version of docker in its repositories, but this version may be outdated. - Please refer to [ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/), [debian](https://docs.docker.com/install/linux/docker-ce/debian/) or [MacOS](https://docs.docker.com/docker-for-mac/install/) documentation to setup a recent version of docker. - -5. Add your current user to the docker group, to allow using docker without `sudo`. - ```bash - # add the docker group if it doesn't already exist - sudo groupadd docker - # add the current user to the docker group - sudo usermod -aG docker $(whoami) - # restart to validate changes - sudo reboot - ``` - -6. Create a docker network for fab-manager. - You may have to change the network address if it is already in use. - ```bash - docker network create --subnet=172.18.0.0/16 fabmanager - ``` - -7. Retrieve the project from Git - - ```bash - git clone https://github.com/sleede/fab-manager.git - ``` - -8. Install the software dependencies. - First install [PostgreSQL](#postgresql) and [ElasticSearch](#elasticsearch) as specified in their respective documentations. - Then install the other dependencies: - - For Ubuntu/Debian: - - ```bash - # on Ubuntu 18.04 server, you may have to enable the "universe" repository - sudo add-apt-repository universe - # then, install the dependencies - sudo apt-get install libpq-dev redis-server imagemagick - ``` - - For MacOS X: - - ```bash - brew install redis imagemagick - ``` - -9. Init the RVM and NVM instances and check they were correctly configured - - ```bash - cd fab-manager - rvm current | grep -q `cat .ruby-version`@fab-manager && echo "ok" - # Must print ok - nvm use - node --version | grep -q `cat .nvmrc` && echo "ok" - # Must print ok - ``` - -10. Install bundler in the current RVM gemset - - ```bash - gem install bundler --version=1.17.3 - ``` - -11. Install the required ruby gems and javascript plugins - - ```bash - bundle install - yarn install - ``` - -12. Create the default configuration files **and configure them!** (see the [environment configuration documentation](doc/environment.md)) - - ```bash - cp config/database.yml.default config/database.yml - cp config/application.yml.default config/application.yml - vi config/application.yml - # or use your favorite text editor instead of vi (nano, ne...) - ``` - -13. Build the databases. - - **Warning**: **DO NOT** run `rake db:setup` instead of these commands, as this will not run some required raw SQL instructions. - - **Please note**: Your password length must be between 8 and 128 characters, otherwise db:seed will be rejected. This is configured in [config/initializers/devise.rb](config/initializers/devise.rb) - - ```bash - # for dev - rake db:create - rake db:migrate - ADMIN_EMAIL='youradminemail' ADMIN_PASSWORD='youradminpassword' rake db:seed - rake fablab:es:build_stats - # for tests - RAILS_ENV=test rake db:create - RAILS_ENV=test rake db:migrate - ``` - -14. Create the pids folder used by Sidekiq. If you want to use a different location, you can configure it in `config/sidekiq.yml` - - ```bash - mkdir -p tmp/pids - ``` - -15. Start the development web server - - ```bash - foreman s -p 3000 - ``` - -16. You should now be able to access your local development FabManager instance by accessing `http://localhost:3000` in your web browser. - -17. You can login as the default administrator using the credentials defined previously. - -18. Email notifications will be caught by MailCatcher. - To see the emails sent by the platform, open your web browser at `http://localhost:1080` to access the MailCatcher interface. - - - -## PostgreSQL - - -### Install PostgreSQL 9.6 - -We will use docker to easily install the required version of PostgreSQL. - -1. Create the docker binding folder - ```bash - mkdir -p .docker/postgresql - ``` - -2. Start the PostgreSQL container. - ```bash - docker run --restart=always -d --name fabmanager-postgres \ - -v $(pwd)/.docker/postgresql:/var/lib/postgresql/data \ - --network fabmanager --ip 172.18.0.2 \ - -p 5432:5432 \ - postgres:9.6 - ``` - -3. Configure fab-manager to use it. - On linux systems, PostgreSQL will be available at 172.18.0.2. - On MacOS, you'll have to set the host to 127.0.0.1 (or localhost). - See [environment.md](doc/environment.md) for more details. - -4 . Finally, you may want to have a look at detailed informations about PostgreSQL usage in fab-manager. - Some information about that is available in the [PostgreSQL Readme](doc/postgresql_readme.md). - - -## ElasticSearch - -ElasticSearch is a powerful search engine based on Apache Lucene combined with a NoSQL database used as a cache to index data and quickly process complex requests on it. - -In FabManager, it is used for the admin's statistics module and to perform searches in projects. - - -### Install ElasticSearch - -1. Create the docker binding folders - ```bash - mkdir -p .docker/elasticsearch/config - mkdir -p .docker/elasticsearch/plugins - mkdir -p .docker/elasticsearch/backups - ``` - -2. Copy the default configuration files - ```bash - cp docker/elasticsearch.yml .docker/elasticsearch/config - cp docker/log4j2.properties .docker/elasticsearch/config - ``` - -3. Start the ElasticSearch container. - ```bash - docker run --restart=always -d --name fabmanager-elastic \ - -v $(pwd)/.docker/elasticsearch/config:/usr/share/elasticsearch/config \ - -v $(pwd)/.docker/elasticsearch:/usr/share/elasticsearch/data \ - -v $(pwd)/.docker/elasticsearch/plugins:/usr/share/elasticsearch/plugins \ - -v $(pwd)/.docker/elasticsearch/backups:/usr/share/elasticsearch/backups \ - --network fabmanager --ip 172.18.0.3 \ - -p 9200:9200 -p 9300:9300 \ - elasticsearch:5.6 - ``` - -4. Configure fab-manager to use it. - On linux systems, ElasticSearch will be available at 172.18.0.3. - On MacOS, you'll have to set the host to 127.0.0.1 (or localhost). - See [environment.md](doc/environment.md) for more details. - - -### Rebuild statistics - -Every nights, the statistics for the day that just ended are built automatically at 01:00 (AM) and stored in ElastricSearch. -See [schedule.yml](config/schedule.yml) to modify this behavior. -If the scheduled task wasn't executed for any reason (eg. you are in a dev environment and your computer was turned off at 1 AM), you can force the statistics data generation in ElasticSearch, running the following command. - -```bash -# Here for the 50 last days -rake fablab:es:generate_stats[50] -``` - - -### Backup and Restore - -To backup and restore the ElasticSearch database, use the [elasticsearch-dump](https://github.com/taskrabbit/elasticsearch-dump) tool. - -Dump the database with: `elasticdump --input=http://localhost:9200/stats --output=fablab_stats.json`. -Restore it with: `elasticdump --input=fablab_stats.json --output=http://localhost:9200/stats`. +Optionally, you can use a virtual development environment that relies on Vagrant and Virtual Box by following the [virtual machine instructions](virtual-machine.md). ## Internationalization (i18n) The FabManager application can only run in a single language but this language can easily be changed. - -### Translation - -Check the files located in `config/locales`: - -- Front app translations (angular.js) are located in `config/locales/app.scope.XX.yml`. - Where scope has one the following meaning : - - admin: translations of the administrator views (manage and configure the FabLab). - - logged: translations of the end-user's views accessible only to connected users. - - public: translation of end-user's views publicly accessible to anyone. - - shared: translations shared by many views (like forms or buttons). -- Back app translations (Ruby on Rails) are located in `config/locales/XX.yml`. -- Emails translations are located in `config/locales/mails.XX.yml`. -- Messages related to the authentication system are located in `config/locales/devise.XX.yml`. - -If you plan to translate the application to a new locale, please consider that the reference translation is French. -Indeed, in some cases, the English texts/sentences can seems confuse or lack of context as they were originally translated from French. - -To prevent syntax mistakes while translating locale files, we **STRONGLY advise** you to use a text editor which support syntax coloration for YML and Ruby. - - -#### Front-end translations - -Front-end translations uses [angular-translate](http://angular-translate.github.io) with some interpolations interpreted by angular.js and other interpreted by [MessageFormat](https://github.com/SlexAxton/messageformat.js/). -**These two kinds of interpolation use a near but different syntax witch SHOULD NOT be confused.** -Please refer to the official [angular-translate documentation](http://angular-translate.github.io/docs/#/guide/14_pluralization) before translating. - - -#### Back-end translations - -Back-end translations uses the [Ruby on Rails syntax](http://guides.rubyonrails.org/i18n.html) but some complex interpolations are interpreted by [MessageFormat](https://github.com/format-message/message-format-rb) and are marked as it in comments. -**DO NOT confuse the syntaxes.** - -In each cases, some inline comments are included in the localisation files. -They can be recognized as they start with the sharp character (#). -These comments are not required to be translated, they are intended to help the translator to have some context information about the sentence to translate. - -You will also need to translate the invoice watermark, located in `app/pdfs/data/`. -You'll find there the [GIMP source of the image](app/pdfs/data/watermark.xcf), which is using [Rubik Mono One](https://fonts.google.com/specimen/Rubik+Mono+One) as font. -Use it to generate a similar localised PNG image which keep the default image size, as PDF are not responsive. - - - -### Configuration - -Locales configurations are made in `config/application.yml`. -If you are in a development environment, your can keep the default values, otherwise, in production, values must be configured carefully. - - -#### Settings - -Please refer to the [environment configuration documentation](doc/environment.md#internationalization-settings) - - -#### Applying changes - -After modifying any values concerning the localisation, restart the application (ie. web server) to apply these changes in the i18n configuration. +Please refer to the [translation readme](doc/translation_readme.md) for instructions about configuring the language or to contribute to the translation. ## Open Projects diff --git a/doc/development_readme.md b/doc/development_readme.md new file mode 100644 index 000000000..a3d3af8f3 --- /dev/null +++ b/doc/development_readme.md @@ -0,0 +1,231 @@ +# Install Fab-Manager in a development environment with Docker + +This document will guide you through all the steps needed to set up a development environment for Fab-Manager. + +##### Table of contents + +1. [General Guidelines](#general-guidelines)
+2. [PostgreSQL](#postgresql)
+2.1. [Install PostgreSQL 9.6](#setup-postgresql) +3. [ElasticSearch](#elasticsearch)
+3.1. [Install ElasticSearch](#setup-elasticsearch)
+3.2. [Rebuild statistics](#rebuild-stats)
+3.3. [Backup and Restore](#backup-and-restore-elasticsearch) + +This procedure is not easy to follow so if you don't need to write some code for Fab-manager, please prefer the [docker-compose installation method](docker-compose_readme.md). + + + +## General Guidelines + +1. Install RVM, with the ruby version specified in the [.ruby-version file](../.ruby-version). + For more details about the process, please read the [official RVM documentation](http://rvm.io/rvm/install). + If you're using ArchLinux, you may have to [read this](archlinux_readme.md) before. + +2. Install NVM, with the node.js version specified in the [.nvmrc file](../.nvmrc). + For instructions about installing NVM, please refer to [the NVM readme](https://github.com/nvm-sh/nvm#installation-and-update). + +3. Install Yarn, the front-end package manager. + Depending on your system, the installation process may differ, please read the [official Yarn documentation](https://yarnpkg.com/en/docs/install#debian-stable). + +4. Install docker. + Your system may provide a pre-packaged version of docker in its repositories, but this version may be outdated. + Please refer to [ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/), [debian](https://docs.docker.com/install/linux/docker-ce/debian/) or [MacOS](https://docs.docker.com/docker-for-mac/install/) documentation to setup a recent version of docker. + +5. Add your current user to the docker group, to allow using docker without `sudo`. + ```bash + # add the docker group if it doesn't already exist + sudo groupadd docker + # add the current user to the docker group + sudo usermod -aG docker $(whoami) + # restart to validate changes + sudo reboot + ``` + +6. Create a docker network for fab-manager. + You may have to change the network address if it is already in use. + >  If you're using MacOS, this is not required. + ```bash + docker network create --subnet=172.18.0.0/16 fabmanager + ``` + +7. Retrieve the project from Git + + ```bash + git clone https://github.com/sleede/fab-manager.git + ``` + +8. Install the software dependencies. + First install [PostgreSQL](#postgresql) and [ElasticSearch](#elasticsearch) as specified in their respective documentations (see below). + Then install the other dependencies: + - For Ubuntu/Debian: + + ```bash + # on Ubuntu 18.04 server, you may have to enable the "universe" repository + sudo add-apt-repository universe + # then, install the dependencies + sudo apt-get install libpq-dev redis-server imagemagick + ``` + - For MacOS X: + + ```bash + brew install redis imagemagick + ``` + +9. Init the RVM and NVM instances and check they were correctly configured + + ```bash + cd fab-manager + rvm current | grep -q `cat .ruby-version`@fab-manager && echo "ok" + # Must print ok + nvm use + node --version | grep -q `cat .nvmrc` && echo "ok" + # Must print ok + ``` + +10. Install bundler in the current RVM gemset + + ```bash + gem install bundler --version=1.17.3 + ``` + +11. Install the required ruby gems and javascript plugins + + ```bash + bundle install + yarn install + ``` + +12. Create the default configuration files **and configure them!** (see the [environment configuration documentation](doc/environment.md)) + + ```bash + cp config/database.yml.default config/database.yml + cp config/application.yml.default config/application.yml + vi config/application.yml + # or use your favorite text editor instead of vi (nano, ne...) + ``` + +13. Build the databases. + - **Warning**: **DO NOT** run `rake db:setup` instead of these commands, as this will not run some required raw SQL instructions. + - **Please note**: Your password length must be between 8 and 128 characters, otherwise db:seed will be rejected. This is configured in [config/initializers/devise.rb](config/initializers/devise.rb) + + ```bash + # for dev + rake db:create + rake db:migrate + ADMIN_EMAIL='youradminemail' ADMIN_PASSWORD='youradminpassword' rake db:seed + rake fablab:es:build_stats + # for tests + RAILS_ENV=test rake db:create + RAILS_ENV=test rake db:migrate + ``` + +14. Create the pids folder used by Sidekiq. If you want to use a different location, you can configure it in `config/sidekiq.yml` + + ```bash + mkdir -p tmp/pids + ``` + +15. Start the development web server + + ```bash + foreman s -p 3000 + ``` + +16. You should now be able to access your local development FabManager instance by accessing `http://localhost:3000` in your web browser. + +17. You can login as the default administrator using the credentials defined previously. + +18. Email notifications will be caught by MailCatcher. + To see the emails sent by the platform, open your web browser at `http://localhost:1080` to access the MailCatcher interface. + + + +## PostgreSQL + + +### Install PostgreSQL 9.6 + +We will use docker to easily install the required version of PostgreSQL. + +1. Create the docker binding folder + ```bash + mkdir -p .docker/postgresql + ``` + +2. Start the PostgreSQL container. + >  If you're using MacOS, remove the --network and --ip parameters, and add -p 5432:5432. + ```bash + docker run --restart=always -d --name fabmanager-postgres \ + -v $(pwd)/.docker/postgresql:/var/lib/postgresql/data \ + --network fabmanager --ip 172.18.0.2 \ + postgres:9.6 + ``` + +3. Configure fab-manager to use it. + On linux systems, PostgreSQL will be available at 172.18.0.2. + On MacOS, you'll have to set the host to 127.0.0.1 (or localhost). + See [environment.md](doc/environment.md) for more details. + +4 . Finally, you may want to have a look at detailed informations about PostgreSQL usage in fab-manager. + Some information about that is available in the [PostgreSQL Readme](doc/postgresql_readme.md). + + +## ElasticSearch + +ElasticSearch is a powerful search engine based on Apache Lucene combined with a NoSQL database used as a cache to index data and quickly process complex requests on it. + +In FabManager, it is used for the admin's statistics module and to perform searches in projects. + + +### Install ElasticSearch + +1. Create the docker binding folders + ```bash + mkdir -p .docker/elasticsearch/config + mkdir -p .docker/elasticsearch/plugins + mkdir -p .docker/elasticsearch/backups + ``` + +2. Copy the default configuration files + ```bash + cp docker/elasticsearch.yml .docker/elasticsearch/config + cp docker/log4j2.properties .docker/elasticsearch/config + ``` + +3. Start the ElasticSearch container. + >  If you're using MacOS, remove the --network and --ip parameters, and add -p 9200:9200. + ```bash + docker run --restart=always -d --name fabmanager-elastic \ + -v $(pwd)/.docker/elasticsearch/config:/usr/share/elasticsearch/config \ + -v $(pwd)/.docker/elasticsearch:/usr/share/elasticsearch/data \ + -v $(pwd)/.docker/elasticsearch/plugins:/usr/share/elasticsearch/plugins \ + -v $(pwd)/.docker/elasticsearch/backups:/usr/share/elasticsearch/backups \ + --network fabmanager --ip 172.18.0.3 \ + elasticsearch:5.6 + ``` + +4. Configure fab-manager to use it. + On linux systems, ElasticSearch will be available at 172.18.0.3. + On MacOS, you'll have to set the host to 127.0.0.1 (or localhost). + See [environment.md](doc/environment.md) for more details. + + +### Rebuild statistics + +Every nights, the statistics for the day that just ended are built automatically at 01:00 (AM) and stored in ElastricSearch. +See [schedule.yml](config/schedule.yml) to modify this behavior. +If the scheduled task wasn't executed for any reason (eg. you are in a dev environment and your computer was turned off at 1 AM), you can force the statistics data generation in ElasticSearch, running the following command. + +```bash +# Here for the 50 last days +rake fablab:es:generate_stats[50] +``` + + +### Backup and Restore + +To backup and restore the ElasticSearch database, use the [elasticsearch-dump](https://github.com/taskrabbit/elasticsearch-dump) tool. + +Dump the database with: `elasticdump --input=http://localhost:9200/stats --output=fablab_stats.json`. +Restore it with: `elasticdump --input=fablab_stats.json --output=http://localhost:9200/stats`. diff --git a/docker/README.md b/doc/docker-compose_readme.md similarity index 100% rename from docker/README.md rename to doc/docker-compose_readme.md diff --git a/doc/translation_readme.md b/doc/translation_readme.md new file mode 100644 index 000000000..17667785f --- /dev/null +++ b/doc/translation_readme.md @@ -0,0 +1,75 @@ +# Fab-Manager translation documentation + +This document will explain you what you need to know to contribute to the translation process of Fab-Manager. + +##### Table of contents + +1. [Translation](#i18n-translation)
+1.1. [Front-end translations](#i18n-translation-front)
+1.2. [Back-end translations](#i18n-translation-back) +2. [Configuration](#i18n-configuration)
+2.1. [Settings](#i18n-settings)
+2.2. [Applying changes](#i18n-apply) + + +## Translation + +First, consider that it can be a good idea to setup a development environment to contribute to the software translation. +This is not mandatory, but this will allow you to test your changes in context and see if anything went wrong, especially with the special syntaxes. +Please refer to the [development readme](development_readme.md) or to the [virtual machine instructions](virtual-machine.md) to setup such an environment. + +Once done, check the files located in `config/locales`: + +- Front app translations (angular.js) are located in `config/locales/app.scope.XX.yml`. + Where scope has one the following meaning : + - admin: translations of the administrator views (manage and configure the FabLab). + - logged: translations of the end-user's views accessible only to connected users. + - public: translation of end-user's views publicly accessible to anyone. + - shared: translations shared by many views (like forms or buttons). +- Back app translations (Ruby on Rails) are located in `config/locales/XX.yml`. +- Emails translations are located in `config/locales/mails.XX.yml`. +- Messages related to the authentication system are located in `config/locales/devise.XX.yml`. + +If you plan to translate the application to a new locale, please consider that the reference translation is French. +Indeed, in some cases, the English texts/sentences can seems confuse or lack of context as they were originally translated from French. + +To prevent syntax mistakes while translating locale files, we **STRONGLY advise** you to use a text editor which support syntax coloration for YML and Ruby. +As an example, [Visual Studio Code](https://code.visualstudio.com/), with the [Ruby extension](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby) and the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) will do the job. + + +### Front-end translations + +Front-end translations uses [angular-translate](http://angular-translate.github.io) with some interpolations interpreted by angular.js and other interpreted by [MessageFormat](https://github.com/SlexAxton/messageformat.js/). +**These two kinds of interpolation use a near but different syntax witch SHOULD NOT be confused.** +Please refer to the official [angular-translate documentation](http://angular-translate.github.io/docs/#/guide/14_pluralization) before translating. + + +### Back-end translations + +Back-end translations uses the [Ruby on Rails syntax](http://guides.rubyonrails.org/i18n.html) but some complex interpolations are interpreted by [MessageFormat](https://github.com/format-message/message-format-rb) and are marked as it in comments. +**DO NOT confuse the syntaxes.** + +In each cases, some inline comments are included in the localisation files. +They can be recognized as they start with the sharp character (#). +These comments are not required to be translated, they are intended to help the translator to have some context information about the sentence to translate. + +You will also need to translate the invoice watermark, located in `app/pdfs/data/`. +You'll find there the [GIMP source of the image](app/pdfs/data/watermark.xcf), which is using [Rubik Mono One](https://fonts.google.com/specimen/Rubik+Mono+One) as font. +Use it to generate a similar localised PNG image which keep the default image size, as PDF are not responsive. + + + +## Configuration + +Locales configurations are made in `config/application.yml`. +If you are in a development environment, your can keep the default values, otherwise, in production, values must be configured carefully. + + +### Settings + +Please refer to the [environment configuration documentation](doc/environment.md#internationalization-settings) + + +### Applying changes + +After modifying any values concerning the localisation, restart the application (ie. web server) to apply these changes in the i18n configuration.