modules/transliteration/README.txt

/* $Id: README.txt,v 1.8 2009/06/10 12:53:47 smk Exp $ */

-- SUMMARY --

The purpose of this module is to provide a central transliteration service for
other Drupal modules, as well as sanitizing file names while uploading files
to Drupal.

For a full description visit the project page:
  http://drupal.org/project/transliteration
Bug reports, feature suggestions and latest developments:
  http://drupal.org/project/issues/transliteration


-- INSTALLATION --

1. Copy the transliteration folder to your modules directory.

2. If you are installing to an existing Drupal site, you might want to enable
   retroactive transliteration during installation of this module. This will
   update all file names containing non-ASCII characters. However, if you have
   hard-coded links in your contents these will be broken and require manual
   fixing. Therefore you have to manually enable this feature by editing
   transliteration.install and change the following line at the top of the file:

     define('TRANSLITERATION_RETROACTIVE', FALSE);

   to

     define('TRANSLITERATION_RETROACTIVE', TRUE);

   If you already installed the module and would like to execute retroactive
   transliteration afterwards, you can rerun update.php and manually select
   update #1.

3. Install as usual, see http://drupal.org/node/70151 for further information.


-- CONFIGURATION --

This module has no settings that can be customized.


-- 3RD PARTY INTEGRATION --

Third party developers who are seeking an easy way to transliterate strings may
use the transliteration_get() helper function:

if (module_exists('transliteration')) {
  $transliterated = transliteration_get($string);
}

You might want to take a look at the PHPDoc for an explanation of additional
function parameters.


-- LANGUAGE SPECIFIC REPLACEMENTS --

This module uses transliteration data collected from various sources which might
be incomplete or inaccurate for your specific language. Therefore,
transliteration supports language specific alterations to the basic
replacements. The following guide explains how to add them:

1. First find the Unicode character code you want to replace. As an example,
   we'll be adding a custom transliteration for the cyrillic character 'г'
   (hexadecimal code 0x0433) using the ASCII character 'q' for Azerbaijani
   input.

2. Transliteration stores its mappings in banks with 256 characters each. The
   first two digits of the character code (04) tell you in which file you'll
   find the corresponding mapping. In our case it is data/x04.php.

3. If you open that file in an editor, you'll find the base replacement matrix
   consisting of 16 lines with 16 characters on each line, and zero or more
   additional language-specific variants. To add our custom replacement, we need
   to do two things: first, we need to create a new transliteration variant
   for Azerbaijani since it doesn't exist yet, and second, we need to map the
   last two digits of the hexadecimal character code (33) to the desired output:

     $variant['az'] = array(0x33 => 'q');

   (see http://people.w3.org/rishida/names/languages.html for a list of
   language codes).

   Any Azerbaijani input will now use the appropriate variant.

Also take a look at data/x00.php which already contains a bunch of language
specific replacements. If you think your overrides are useful for others please
create and file a patch at http://drupal.org/project/issues/transliteration.


-- CREDITS --

Authors:
* Stefan M. Kudwien (smk-ka) - http://drupal.org/user/48898
* Daniel F. Kudwien (sun) - http://drupal.org/user/54136

UTF-8 normalization is based on UtfNormal.php from MediaWiki
(http://www.mediawiki.org) and transliteration uses data from Sean M. Burke's
Text::Unidecode CPAN module
(http://search.cpan.org/~sburke/Text-Unidecode-0.04/lib/Text/Unidecode.pm).

This project has been sponsored by UNLEASHED MIND
Specialized in consulting and planning of Drupal powered sites, UNLEASHED
MIND offers installation, development, theming, customization, and hosting
to get you started. Visit http://www.unleashedmind.com for more information.

1	/* $Id: README.txt,v 1.8 2009/06/10 12:53:47 smk Exp $ */
2
3	-- SUMMARY --
4
5	The purpose of this module is to provide a central transliteration service for
6	other Drupal modules, as well as sanitizing file names while uploading files
7	to Drupal.
8
9	For a full description visit the project page:
10	http://drupal.org/project/transliteration
11	Bug reports, feature suggestions and latest developments:
12	http://drupal.org/project/issues/transliteration
13
14
15	-- INSTALLATION --
16
17	1. Copy the transliteration folder to your modules directory.
18
19	2. If you are installing to an existing Drupal site, you might want to enable
20	retroactive transliteration during installation of this module. This will
21	update all file names containing non-ASCII characters. However, if you have
22	hard-coded links in your contents these will be broken and require manual
23	fixing. Therefore you have to manually enable this feature by editing
24	transliteration.install and change the following line at the top of the file:
25
26	define('TRANSLITERATION_RETROACTIVE', FALSE);
27
28	to
29
30	define('TRANSLITERATION_RETROACTIVE', TRUE);
31
32	If you already installed the module and would like to execute retroactive
33	transliteration afterwards, you can rerun update.php and manually select
34	update #1.
35
36	3. Install as usual, see http://drupal.org/node/70151 for further information.
37
38
39	-- CONFIGURATION --
40
41	This module has no settings that can be customized.
42
43
44	-- 3RD PARTY INTEGRATION --
45
46	Third party developers who are seeking an easy way to transliterate strings may
47	use the transliteration_get() helper function:
48
49	if (module_exists('transliteration')) {
50	$transliterated = transliteration_get($string);
51	}
52
53	You might want to take a look at the PHPDoc for an explanation of additional
54	function parameters.
55
56
57	-- LANGUAGE SPECIFIC REPLACEMENTS --
58
59	This module uses transliteration data collected from various sources which might
60	be incomplete or inaccurate for your specific language. Therefore,
61	transliteration supports language specific alterations to the basic
62	replacements. The following guide explains how to add them:
63
64	1. First find the Unicode character code you want to replace. As an example,
65	we'll be adding a custom transliteration for the cyrillic character 'г'
66	(hexadecimal code 0x0433) using the ASCII character 'q' for Azerbaijani
67	input.
68
69	2. Transliteration stores its mappings in banks with 256 characters each. The
70	first two digits of the character code (04) tell you in which file you'll
71	find the corresponding mapping. In our case it is data/x04.php.
72
73	3. If you open that file in an editor, you'll find the base replacement matrix
74	consisting of 16 lines with 16 characters on each line, and zero or more
75	additional language-specific variants. To add our custom replacement, we need
76	to do two things: first, we need to create a new transliteration variant
77	for Azerbaijani since it doesn't exist yet, and second, we need to map the
78	last two digits of the hexadecimal character code (33) to the desired output:
79
80	$variant['az'] = array(0x33 => 'q');
81
82	(see http://people.w3.org/rishida/names/languages.html for a list of
83	language codes).
84
85	Any Azerbaijani input will now use the appropriate variant.
86
87	Also take a look at data/x00.php which already contains a bunch of language
88	specific replacements. If you think your overrides are useful for others please
89	create and file a patch at http://drupal.org/project/issues/transliteration.
90
91
92	-- CREDITS --
93
94	Authors:
95	* Stefan M. Kudwien (smk-ka) - http://drupal.org/user/48898
96	* Daniel F. Kudwien (sun) - http://drupal.org/user/54136
97
98	UTF-8 normalization is based on UtfNormal.php from MediaWiki
99	(http://www.mediawiki.org) and transliteration uses data from Sean M. Burke's
100	Text::Unidecode CPAN module
101	(http://search.cpan.org/~sburke/Text-Unidecode-0.04/lib/Text/Unidecode.pm).
102
103	This project has been sponsored by UNLEASHED MIND
104	Specialized in consulting and planning of Drupal powered sites, UNLEASHED
105	MIND offers installation, development, theming, customization, and hosting
106	to get you started. Visit http://www.unleashedmind.com for more information.
107