Apertium-html-tools

Apertium Html-tools is a web application providing a fully localised interface for translation, analyzation, and generation powered by Apertium. Designed to use only static resources for quick and easy deployment with any web server, it is relatively lightweight and user-friendly. It is currently located in SVN at /trunk/apertium-tools/apertium-html-tools. Html-tools relies on an Apertium HTTP API such as Apertium-apy or ScaleMT (to a lesser extent).

Usage

Getting Started

Using Html-tools is as easy as checking out from SVN, changing the configuration and running make.

   $ svn co https://svn.code.sf.net/p/apertium/svn/trunk/apertium-tools/apertium-html-tools/
   $ vim ./assets/js/config.js #Edit the configuration, see next section for more details
   $ make

The last step is pointing your web server of choice, e.g. Apache, to serve the directory.

Configuration

Since Html-tools is powered entirely by static resources, a configuration file located at /assets/js/config.js is maintained to allow users to modify basic environment parameters such as API location and enabled interfaces. Following is a summary of the currently supported arguments with some examples:

• APY_URL: the URL of an API instance (ScaleMT for basic functionality, APY for full) that the web application calls
  • 'http://www.apertium.org:8080'
  • 'http://localhost:2737'
  • 'https://api.apertium.org'
• ALLOWED_LANGS: an array of ISO 639-3 language codes that the application displays in the interface, useful for deploying websites that have only a subset of all the languages the API being used provides (e.g. a region specific website)
  • undefined does not limit the languages displayed (everything the API supports will be shown).
  • ['tur', 'uzb', 'kaz'] limits to only language pairs between Turkic, Kazakh, and Uzbek will appear in the interface; analyzers and generators for the three languages will also be shown.
  • [] limits the interface to 0 languages (since none are in the array); why would you want to do this? I don't know, but now you know how to.
• ALLOWED_VARIANTS: an array of variant codes that the application displays in the interface, similar to the functionality of ALLOWED_LANGS
  • undefined does not limit the variants displayed (everything the API supports will be shown).
  • ['US', 'GB'] limits languages displayed in the translation interface such that pairs either have no variant or a subset of {'US', 'GB'} (en_US-es and es-en_GB are fine but en_UK-anything is not); analyzers and generators are similarly restricted.
• ENABLED_MODES: an array of the enabled interfaces, a non-empty subset of ['translation', 'analyzation', 'generation', 'sandbox']
  • ['translation'] limits the interface to only translation support.
  • ['translation', 'analyzation', 'generation'] displays the three main interfaces as tabs.
  • ['translation', 'analyzation', 'generation', 'sandbox'] is generally not recommended outside of a development environment since users most probably do not need an API Sandbox.
• DEFAULT_MODE: the default landing interface for a new user, an element of the ENABLED_MODES array
  • 'translation' lets the user land on the translation interface first (recommended option).
• SHOW_NAVBAR: whether the navigation bar that allows switching between interfaces is visible.
  • true shows the navbar and is recommended when more than one mode is enabled via ENABLED_MODES.
  • false hides the navbar and is recommended when only one mode is enabled (e.g. ENABLED_MODES = ['translation']).
• GOOGLE_ANALYTICS_PROPERTY: the Google Analytics property name
  • undefined disables Google Analytics (recommended unless you know what you're doing).
• GOOGLE_ANALYTICS_TRACKING_ID: the Google Analytics tracking code
  • undefined disables Google Analytics (recommended unless you know what you're doing).
• LIST_REQUEST_CACHE_EXPIRY: cache expiry time in hours for /list requests (/listPairs, /list?q=analyzers, /list?q=generators)
  • 24 ensures list requests are refreshed at least every day.
• LANGUAGE_NAME_CACHE_EXPIRY: cache expiry time in hours for /languageName requests
  • 24 ensures language name caches are refreshed at least very 24 hours.
• LOCALIZATION_CACHE_EXPIRY: cache expiry time in hours for localised string asset requests (e.g. /assets/strings/fra.json)
  • 24 ensures the interface strings for a locale are refreshed at least every day (browser caching may interfere).
• AVAILABLE_LOCALES_CACHE_EXPIRY: cache expiry time in hours for available localisations requests (/assets/strings/locales.json)
  • 24 ensures the available locales menu is updated at least every day (browser caching may interfere).

Minification

Minification of static resources is standard procedure and since Html-tools attempts to be self-sufficient with very negligible work required on the server side, a small utility for such a procedure is included.

Minification usage guide

Production

In a production environment, make will generate all the necessary files including the index.html linking to the minified JS and CSS. So, see the instructions in the above section and you should be set for deployment.

Development

Since running make generates an index.html with links to minified content, development is a little bit more complicated. After making changes to any CSS or JS resource and before re-running make, the changes will not be reflected in / since index.html still links to the stale minified CSS or JS resources. While this could be amended by running make after every change, that's a terrible workflow unless it's automated somehow. To alleviate this problem, running make also generates index.debug.html which links to the raw CSS/JS resources that you modify. So, use /index.debug.html while debugging/adding features in the CSS or JS. Modifying the HTML does require running make every time but such changes are less frequent and usually involve less debugging. If you add a static resource (e.g. a new JS file for a spell checker interface), be sure to edit the Makefile and debug-head.html to ensure the minification process still runs smoothly.

Future Improvements

Localisation

The Html-tools interface is fully localisable and has middling support for RTL languages (mostly because it hasn't been localised into any yet). The 16 currently available languages are Aragonese (ara), Avar (ava), Catalan (cat), English (eng), Basque (eus), French (fra), Kazakh (kaz), Kyrgyz (kir), Nynorsk Norwegian (nno), Bokmål Norwegian (nob), Portuguese (por), Romanian (ron), Saami (sme), Spanish (spa), Tatar (tat).

Contributing a new translation of the interface is encouraged and a very simple process.

1. Look at a deployed version of the html-tools interface, preferably one with all/most modes enabled. See the section on deployed sites for where to go.
2. Make a copy of assets/strings/eng.json, replacing 'eng' with your language's ISO 639-6 code.
3. Change all the right-hand values in each pair to match your language, use the website you found from Step 1 to help with context.
4. Optional: Add a line to assets/strings/locales.json with the language code mapped to the language's native name (endonym).
5. Commit to SVN.
6. If you didn't edit locales.json, let us know in IRC so that we can edit it for you and update websites. Thanks!

Todo

• More search engine optimisation (look into possibly compromising some of the static file paradigm in a fork)
• CORS compliance
• Maintaining order of user interactions
• Document translation (requires work on APY)
• Spell checker (requires work on APY)
• RTL language support
• Expanding textareas
• Clear input button
• Language variant picker