README.txt

   1 \feff
   2 -- SUMMARY --
   3
   4 Provides a central transliteration service to other Drupal modules, and
   5 sanitizes file names while uploading.
   6
   7 For a full description visit the project page:
   8   http://drupal.org/project/transliteration
   9 Bug reports, feature suggestions and latest developments:
  10   http://drupal.org/project/issues/transliteration
  11
  12
  13 -- INSTALLATION --
  14
  15 1. Install as usual, see http://drupal.org/node/70151 for further information.
  16
  17 2. If you are installing to an existing Drupal site, you might want to fix
  18    existing file names after installation, which will update all file names
  19    containing non-ASCII characters. However, if you have manually entered links
  20    to those files in any contents, these links will break since the original
  21    files are renamed. Therefore it is a good idea to test the conversion
  22    first on a copy of your web site. You'll find the retroactive conversion at
  23    Configuration and modules >> Media >> File system >> Transliteration.
  24
  25
  26 -- CONFIGURATION --
  27
  28 This module doesn't require special permissions.
  29
  30 This module can be configured from the File system configuration page
  31 (Configuration and modules >> Media >> File system >> Settings).
  32
  33 - Transliterate file names during upload: If you need more control over the
  34   resulting file names you might want to disable this feature here and install
  35   the FileField Paths module (http://drupal.org/project/filefield_paths)
  36   instead.
  37
  38 - Lowercase transliterated file names: It is recommended to enable this option
  39   to prevent issues with case-insensitive file systems.
  40
  41
  42 -- 3RD PARTY INTEGRATION --
  43
  44 Third party developers seeking an easy way to transliterate text or file names
  45 may use transliteration functions as follows:
  46
  47 if (function_exists('transliteration_get')) {
  48   $transliterated = transliteration_get($text, $unknown, $source_langcode);
  49 }
  50
  51 or, in case of file names:
  52
  53 if (function_exists('transliteration_clean_filename')) {
  54   $transliterated = transliteration_clean_filename($filename, $source_langcode);
  55 }
  56
  57 Note that the optional $source_langcode parameter specifies the language code
  58 of the input. If the source language is not known at the time of transliter-
  59 ation, it is recommended to set this argument to the site default language:
  60
  61   $output = transliteration_get($text, '?', language_default('language'));
  62
  63 Otherwise the current display language will be used, which might produce
  64 inconsistent results.
  65
  66
  67 -- LANGUAGE SPECIFIC REPLACEMENTS --
  68
  69 This module supports language specific variations in addition to the basic
  70 transliteration replacements. The following guide explains how to add them:
  71
  72 1. First find the Unicode character code you want to replace. As an example,
  73    we'll be adding a custom transliteration for the cyrillic character 'г'
  74    (hexadecimal code 0x0433) using the ASCII character 'q' for Azerbaijani
  75    input.
  76
  77 2. Transliteration stores its mappings in banks with 256 characters each. The
  78    first two digits of the character code (04) tell you in which file you'll
  79    find the corresponding mapping. In our case it is data/x04.php.
  80
  81 3. If you open that file in an editor, you'll find the base replacement matrix
  82    consisting of 16 lines with 16 characters on each line, and zero or more
  83    additional language-specific variants. To add our custom replacement, we need
  84    to do two things: first, we need to create a new transliteration variant
  85    for Azerbaijani since it doesn't exist yet, and second, we need to map the
  86    last two digits of the hexadecimal character code (33) to the desired output
  87    string:
  88
  89      $variant['az'] = array(0x33 => 'q');
  90
  91    (see http://people.w3.org/rishida/names/languages.html for a list of
  92    language codes).
  93
  94    Any Azerbaijani input will now use the appropriate variant.
  95
  96 Also take a look at data/x00.php which already contains a bunch of language
  97 specific replacements. If you think your overrides are useful for others please
  98 file a patch at http://drupal.org/project/issues/transliteration.
  99
 100
 101 -- CREDITS --
 102
 103 Authors:
 104 * Stefan M. Kudwien (smk-ka) - http://drupal.org/user/48898
 105 * Daniel F. Kudwien (sun) - http://drupal.org/user/54136
 106
 107 Maintainers:
 108 * Andrei Mateescu (amateescu) - http://drupal.org/user/729614
 109
 110 UTF-8 normalization is based on UtfNormal.php from MediaWiki
 111 (http://www.mediawiki.org) and transliteration uses data from Sean M. Burke's
 112 Text::Unidecode CPAN module
 113 (http://search.cpan.org/~sburke/Text-Unidecode-0.04/lib/Text/Unidecode.pm).
 114
 115
 116 -- USEFUL RESOURCES --
 117
 118 Unicode Code Converter:
 119 http://people.w3.org/rishida/tools/conversion/
 120
 121 UTF-8 encoding table and Unicode characters:
 122 http://www.utf8-chartable.de/unicode-utf8-table.pl
 123
 124 Country codes:
 125 http://www.loc.gov/standards/iso639-2/php/code_list.php