L10n by bvanderlaan

L10n allows you to search for and input phrases that have known good translations in multiple other languages so you can save the turn around time of getting phrases translated and vetted by reusing pre-translated and vetted phrases your organization has already used.

When inputting new phrases you provide the local language version of the phrase (in my case English) and a comment explaining the context of the phrase, something that explains the usage of the phrase to help translators choose which version of a word to use. Then once you have translations which you know are good for your context and the target language you can add the translations of the phrase. You can add one translated form of a phrase per target language; Not all phrases need to be translated into each target langauge and you can add or update translations at any time.

Why L10n?

Lets say you create an application, or documentation for that matter, which will be used in multiple region and therefore you choose to localize the text so that your users who read other languages will have an easier time using your application. You probably contract out the translations to a firm; the process is generally to scrape out all the phrases you need translated with context comments, ship them over to the translators, wait, then insert the now translated strings into your application via whatever localization framework your using. L10n is here to address the waiting part of that process.

If you have multiple applications all being translated into the same languages you will probably start to have some overlapping phrases. If your translation firm is good they probably have a phrase map so they won't charge you extra to re-translate phrases you already had them translate (although they will probably charge to you context check them) however you will still have to wait for them to get back to you which can be anywhere from a few days to a couple weeks depending on their throughput, contract agreement, and number of phrases needing to be translated. If the bulk of the phrases are already known wouldn't it be nice if you could just look them up in a local database?

With L10n you can input all the phrases which you have already gotten translated and have checked internally to make sure they are good for your context into a searchable database so that future projects can look up known good pre-translated phrase which they could use to avoid the turn around times.

If one project has already waited the days/weeks to get a set of phrases translated and some of those phrases are words like "Save" or "Delete" as used in a file header bar or "Ok" and "Cancel" as used on a prompt then they could via L10n's web user interface add the phrases to L10n's database complete with context comments (i.e. "Cancel" - "Text used in a button on a prompt meant to terminate an operation") then future projects who are adding a file header bar or confirmation prompts could look up those phrases via L10n's web user interface and find all the known good translations for those phrase thus saving them the turn around time to get them retranslated and revetted by the translation firm.

What you get with L10n

When you setup a L10n server you get a database and an easy to use web based interface.

L10n on Docker

There is a Docker image for L10n which allows you to spin up a L10n application quickly and easily. You can even use docker-compose to build a virtual network with a MySQL backend and a L10n front end running on different container.

The Docker-ized version of L10n only requires the setting of a few environment variables When starting up the container.

Example of Docker command

            
docker run -e SECRET_KEY_BASE=***** -e L10N_DATABASE=l10n_production -e L10N_DATABASE_USER=l10nadmin -e L10N_DATABASE_PASSWORD=**** -e DATABASE_URL=mysql2://l10ndbserver.local:3306/l10n_production l10n:latest

Example of Docker-Compose script

The above command still looks large but like I said you can use docker-compose to script it.

            
version: '2'
services:
  web:
      container_name: l10n
      image: l10n:latest
      environment:
          - SECRET_KEY_BASE=mySuperSecretKeyThatYouCanNeverGuess
          - L10N_DATABASE=l10n_production
          - L10N_DATABASE_USER=l10nadmin
          - L10N_DATABASE_PASSWORD=myl10npassword
          - DATABASE_URL=mysql2://l10ndb:3306/l10n_production
      ports:
          - "8080:3000" # Expose L10n's WUI on http://localhost:8080
      links:
          - db:l10ndb # Setup virtual network between this container and l10ndb
      command: bash -c "rake db:migrate && rake db:seed && rails s -p 3000 -b '0.0.0.0'"
      restart: always # If the container crashes restart it
  db:
      container_name: l10ndb
      image: mysql:5.7.12 # Offical MySQL Image
      environment:
          - MYSQL_ROOT_PASSWORD=myrootpassword
          - MYSQL_PASSWORD=myl10npassword # Same as L10N_DATABASE_PASSWORD
          - MYSQL_USER=l10admin # Same as L10N_DATABASE_USER
          - MYSQL_DATABASE=l10n_production # Same as L10N_DATABASE
      volumes:
          - /mnt/DB/l10ndb:/var/lib/mysql # This saves the database files to the host so you can destroy the l10ndb container and not loose data
      command: [mysqld, --character-set-server=utf8mb4, --collation-server=utf8mb4_unicode_ci] # These flags add unicode support for languages such as Japanese and Russian
      restart: always # If the container crashes restart it

For more infromation on how to use the Docker image to setup a L10n server see L10n-Docker.

Manual Installation of L10n

L10n is a Ruby-on-Rails app which by default connects to a MySQL database. You can configure L10n to use a different SQL database if you so choose by updating the config/database.yml file.

To install L10n from scratch you will need to have Ruby-on-Rails 4 and the Bundler gem installed. You will also need to install MySQL, or whichever SQL database you plan to use for L10n. The SQL database can be on the same server as L10n or hosted on a different server which L10n will be able to connect to. Once installed perform the following:

Clone the repository.
git clone https://github.com/bvanderlaan/L10n.git
Navigate into the repositories root folder.
cd L10n
Checkout which version of L10n you want. To use the latest and greatest yet unreleased version use the master branch.
git checkout v1.0.0
Install the required gems via bundler
$ bundle install

By default L10n is setup to use MySQL (See config/database.yml). The next steps is to setup a database on your MySQL server for L10n to use.

Log into your MySQL server as a root user.

                
$ mysql -u root -p
Enter password: *<your root password>*

Now grant privileges to the user that L10n will use to interact with the database. The user L10n will use is defiend in config/database.yml. The default user name is l10n and the default production database is called l10n_production.
```
                
mysql> grant all privileges on l10n_production.*
        -> to 'l10n'@'localhost'
        -> identified by '*<your l10n user password>*';
                
              
```
At this point you can log out of mysql (remember your logged in as the root user) and log back in as the l10n user.
```
                
mysql> exit;
$ mysql -u l10n -p
Enter password: *<your l10n password>*
                
              
```
Alright you've proven that your database is ready to go. You can log out of mysql now if you like.
Back in a terminal you can now create and populate the database with the required tables and entries using Rake (Rake is a tool which comes with Ruby-on-Rails).
$ RAILS_ENV=production rake db:setup
Next you need to pre-compile the static assets. Rails has an asset pipeline which allows you to use languages like TypeScript and SASS, languages which are nicer to develop in but web browsers don't understand, then transplie them into JavaScript and CSS when you release. In Development mode these assets are transpiled on the fly which is nice for develpoment but you do take a performance hit. In production mode, the mode we have been setting L10n up to run in, we want to transplie these assets once since they won't change.

This is a must step as this one time transpiling will place the assets in a different directory, a directory L10n will look for in production mode that differs then when run in Develpoment mode. The point, if you don't do this L10n won't be able to find the CSS, JavaScript, and Image files.

Luckally Rails has a tool to make this easy.
Back in a terminal execute the following Rake command.
$ RAILS_ENV=production rake assets:precompile
Lastly you can now start up the Rails server. There is no need to install a web server because Rails applications are self hosting via an in memory web server which comes with Rails. Simply execute the following command to start the L10n application.
```
                  
$ RAILS_ENV=production RAILS_SERVE_STATIC_FILES true SECRET_KEY_BASE=auniquesecretkeyusedtoverifysecuredcookies DATABASE_URL=mysql2://yoursqlserver.local:3306/l10n_production rails server -p 3000 -b '0.0.0.0'
                  
                
```
L10n's default port (per Rails convension) is 3000 but you can change it via the -p arguemnt seen above.

The environment variables you set at the beginning of the above command get passed into the L10n app which helps it to start up correctly.
- RAILS_ENV - This tells L10n (or rather Rails) to start up in the Production environment.
- RAILS_SERVE_STATIC_FILES - This tells L10n (or rather Rails) that you have pre-compiled your static assets.
- SECRET_KEY_BASE - L10n will use this 128 character key to verify the integrity of signed cookies. You can type in any key here you want or you can use rake secret to generate one. Its a secret though so Shhhh
- DATABASE_URL - This is the url L10n will use to connect to the database. Example: mysql2://mysqlserver.local/somedatabase
There you go, now if you navigate to http://localhost:3000, or which ever port you used, on the server running L10n you should see the L10n home page.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/bvanderlaan/L10n. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The application is available as open source under the terms of the Apache License, version 2.0.