Difference between revisions of "Apertium-html-tools"

From Apertium
Jump to navigation Jump to search
(some config stuff)
Line 13: Line 13:
 
$ make
 
$ make
 
</code>
 
</code>
  +
  +
The last step is pointing your web server of choice, e.g. Apache, to serve the directory.
   
 
=== Configuration ===
 
=== Configuration ===
  +
Since Html-tools is powered entirely by static resources, a configuration file located at [https://svn.code.sf.net/p/apertium/svn/trunk/apertium-tools/apertium-html-tools/assets/js/config.js /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
  +
** <code>'http://www.apertium.org:8080'</code>
  +
** <code>'http://localhost:2737'</code>
  +
** <code>'https://turkic.apertium.com:8888'</code>
  +
* '''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)
  +
** <code>undefined</code> does <strong>not</strong> limit the languages displayed (everything the API supports will be shown).
  +
** <code>['tur', 'uzb', 'kaz']</code> 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.
  +
** <code>[]</code> 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
  +
** <code>undefined</code> does <strong>not</strong> limit the variants displayed (everything the API supports will be shown).
  +
** <code>['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 <strong>non-empty</strong> subset of ['translation', 'analyzation', 'generation', 'sandbox']
  +
** <code>['translation']</code> limits the interface to only translation support
  +
** <code>['translation', 'analyzation', 'generation']</code> displays the three main interfaces as tabs
  +
** <code>['translation', 'analyzation', 'generation', 'sandbox']</code> 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
  +
** <code>'translation'</code> lets the user land on the translation interface first (recommended option)
  +
* '''SHOW_NAVBAR''': whether the navigation bar that allows switching between interfaces is visible
  +
** <code>true</code> shows the navbar and is recommended when more than one mode is enabled via ENABLED_MODES
  +
** <code>false</code> hides the navbar and is recommended when only one mode is enabled (e.g. ENABLED_MODES = <code>['translation']</code>)
  +
* '''GOOGLE_ANALYTICS_PROPERTY''': the Google Analytics property name
  +
** <code>undefined</code> disables Google Analytics (recommended unless you know what you're doing)
  +
* '''GOOGLE_ANALYTICS_TRACKING_ID''': the Google Analytics tracking code
  +
** <code>undefined</code> 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)
  +
** <code>24</code> ensures list requests are refreshed at least every day
  +
* '''LANGUAGE_NAME_CACHE_EXPIRY''': cache expiry time in hours for /languageName requests
  +
** <code>24</code> 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)
  +
** <code>24</code> 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)
  +
** <code>24</code> ensures the available locales menu is updated at least every day (browser caching may interfere)
   
 
=== Minification ===
 
=== Minification ===
  +
Minification of static resources in 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.
  +
  +
==== Production ====
  +
  +
==== Development ====
   
 
== Current Status ==
 
== Current Status ==

Revision as of 14:07, 24 April 2014

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
  • 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 in 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.

Production

Development

Current Status

Features

Deployed Examples

Future Improvements

Localisation

Todo