Contents
Short description
yvTransliterate is Transliteration
plugin for Joomla!
1.5. The plugin transliterates article titles into aliases, taking into
account "Content Language"of the Article (stored in metadata
of the Article) and it also transliterates aliases of other elements of
Joomla! site interface (menu items, sections, categories...), that are
used in Search engine optimization (SEO) for creation of Search engine
friendly (SEF) slugs (URLs). List of supported languages/transliteration
tables is expandable with Language packs.
As of 2009-02-27
yvTransliterate has transliterations for five languages: Czech,
Hungarian, Russian, Slovak and Ukrainian, and it has 'Language pack
template', that may be easily adapted for new languages.
The extension may be used for the site, that uses only one
non-English language, but it is especially useful and unique for
multilingual sites, where different articles are written in different
languages (even in one session by single user) and so, should be
transliterated by different rules.
It doesn't require any hack to the code of Joomla!'s core: you
simply have to install one plugin and as many
yvTransliterateLanguagePacks, as you need.
yvTransliterate supports PHP5 only (although it may work
under PHP4...).
Terms
of use: Copyright (C) 2007-2008 Yuri
Volkov, Moscow, Russia.
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License, version 2, as published
by the Free Software Foundation. This program is distributed in the hope
that it will be useful, but WITHOUT ANY WARRANTY; without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
Demo sites: (None yet...)
Your
contribution is needed!
- Donate
to help sustain this project.
Troubleshooting and 'Before you
begin'
- If you have any problem, please read this page from the very
top to the bottom - it is being maintained exactly for this purpose: to
save your time, to make your questions answered and problems solved.
- In order to understand, what yvTransliterate is doing, you may
turn on "Debugging mode" in parameters of the plugin.
- If you got this error message during installation of
yvTransliterate: 'Error! Could not find an XML setup file in the
package.' - this means, that you didn't read instructions below
(in this
case, Section "1. Installation of Joomla! and it's extension(s)"):
yvTransliterate.zip is NOT installable file.
- To minimize chance of problems, my advice is to use PHP5 and
MySQL5. And don't use "legacy mode" in Joomla! until it's absolutely
necessary for you.
- Please note, that I didn't test vTransliterate in
"legacy mode" of Joomla! ...
- Current version of yvTransliterate requires Joomla!
1.5.4 or newer. Moreover, it definitely doesn't work on older builds of
Joomla! 1.5.
So, if you have some problem, start with moving (at your test site, not
at production site!) to the newest build of Joomla!.
- If you still have problem, please read messages in this Joomla! forum. Maybe, your questions were
answered already.
- If you believe you found a bug in yvTransliterate and you want
to make yvTransliterate better, please describe the problem in details,
including:
- exact Joomla! version number,
- exact version of yvComment,
- scenario (steps) to reproduce the problem.
- and send your report to the JoomlaCode Tracker: we may discuss that bug there
and ensure it won't be forgotten.
Good luck and let's go!
Upgrading existing installation of yvTransliterate
If you're not upgrading existing installation of yvTransliterate,
please skip this section.
The only reliable way to upgrade existing installation of
yvTransliterate is to uninstall it (uninstall plugin), and then install
new version (as it is described below). To upgrade language pack, you
have to uninstall this language pack only and then install newer one.
These are "yvTransliterate plugin" parameters, that are not
preserved during upgrade, and you have to set them again after
installation. To speed up setting of parameters (and to be sure, that
you didn't forget something...), I recommend to open yvTransliterate
plugin parameters in new window of your Internet browser before
uninstall, leave it open, and use information from this window as a
reference for setting parameters of newer version. After uninstallation
of old version, installation and configuring of newer one, please close
this "reference window". And don't press any buttons on it!
Installation and configuration
1. Installation of Joomla! and it's
extension(s)
- In a case of any problem during installation, please refer to
the Troubleshooting section above.
- It is recommended to have Joomla! 1.5.4 (Stable) or newer,
because yvTransliterate is not tested to work with earlier builds of
Joomla! (In any case you MUST have at least Joomla! 1.5.3. If
this is not a case, do not waste your time trying to install
yvTransliterate ).
- For each yvCommentLanguagePack, that you are planning to
install, please install 'full' language pack of Joomla! for this
language for Administrator interface, downloading it e.g. from Joomla! Accredited Translations.
- Install yvTransliterate itself.
- It is required to install "yvTransliterate
Plugin"to install (download).
- yvTransliterate distribution package contains English
language files only, and in fact, this package has no
transliterations. So you need to download some of
yvTransliterateLanguagePacks from JoomlaCode and install them.
(yvTransliterateLanguagePacks should not be enabled!)
Now you may continue to the "Preparing for
configuration" below.
2. Preparing for configuration
Before going to the configuration, you have to make some
additional steps in Administrator interface (backend):
- (None yet)
Now you may continue to the "Step-by-step
configuration" below.
- First thing to do is to open yvTransliterate plugin
configuration page: in the menu Extensions->Plugin Manager->click
"yvTransliterate" Plugin.
You will see something similar to the picture to the right.
"Extend content table" - set
to "Yes" to allow yvTransliterate to add Article alias transliteration
functionality without any patch of Joomla! core.
How this works:
- Plugin integrates itself into the JTableContent::check()
function, that is called just before Article (or Comment in a case of
yvComment) is saved (after creation/editing).
- If alias is not empty, it does nothing (e.g. when user typed
alias manually).
- If alias is empty, yvTransliterate transliterates article
'title' and puts result into 'alias'.
So, it works naturally for new articles (if you leave alias
empty!) or for old articles, if you clear alias before saving your
article.
- "Extend JLanguage class" - set to "Yes" to
allow yvTransliterate to add another 'hook' into Joomla! core.
This allows yvTransliterate to transliterate not only aliases of
Articles, but aliases of other elements of Joomla! site interface also:
menu items, sections, categories... in fact, yvTransliterate works in
every place, where Joomla! core calls JLanguage::transliterate method.
Please note, that in this case yvTransliterate uses current
Language of user interface (i.e. of current user) as source Language
for transliteration. So, for example, if you want Section alias to be
transliterated according to Russian transliteration table, you have to
log in to Administrator site (backend) in Russian language.
- "Default content language" - If the value of
this option was not selected, the language defaults to current Language
of User interface.
- Group of settings, starting from "Debugging mode"
is used in Debugging mode only, so there is no need in them until you
can't understand, what's going on.
Anyway "Transliteration name" should be left empty (so the
plugin will use 'default' name).
- Enable plugin (in 'Details' box to the left set 'Enabled'
option to 'Yes').
- Save new configuration of the yvTransliterate Plugin.
Some tips
- yvTransliterate doesn't require user (both in frontend and in
backend) to explicitly set 'Content language' of the article, only
if current language of User interface is the same as 'Content language'
of the article. E.g., if you logged in Joomla! site and current
language is Czech, yvTransliterate will use 'Czech to English'
transliteration by default. If in this scenario, you want to create
article in e.g. Russian language, you have to set 'Content language' of
the article explicitly in order to tell yvTransliterate, that it needs
to use "Russian to English" transliteration for this article.
- Currently built-in Joomla!'s "Submit an Article" menu item
doesn't allow to set 'Content language' of the article in the frontend
(there is no such an option in "Article Submission Layout"), so in the
frontend yvTransliterate will work correctly for one language only:
current language of user interface.
- If you logged in using English interface,
yvTransliterate won't (by default!) transliterate any menu items,
sections, categories... because that elements doesn't have any
information about their content language. So yvTransliterate doesn't
know, which (if any) language of transliteration to use. v.1.02 adds
"Default content language" option to solve this problem
and to change default content language to any language you want...
Feedback
Your feedback is greatly appreciated!
- If you found a bug in yvTransliterate, or
even developed a fix for it; if you created new translation
or updated existing one - please, send them to the author!
- If you want to discuss yvTransliterate with
Joomla! community, please go to the Joomla! forum. Please refer to the "TODO" section
below before posting Your suggestions.
- If you want to write your review of
yvTransliterate or to read other user's reviews, please go to the Joomla! Extensions Directory. Please, help others
to make the right choice !
- If you want to take part in the development,
you're welcome, and there is always work for you: you may start from
reading TODO list below or propose your idea... In any case: please
write me!
TODO - Future plans and thoughts
Information for Developers
This plugin is the result of the work, that was started in March
2007 (see the thread). I hoped, that this _real_
Transliteration functionality will be inserted in Joomla! 1.5 core, but
it's not there yet (see 'Language slugs transliteration').
yvTransliterate has open and simple interface, that uses special
triggered event, so it may also be used by (integrated in) any other
Joomla! extension to transliterate text strings.
yvTransliterate is written from scratch specifically for Joomla!
1.5 and it is not compatible with previous versions of Joomla!/Mambo. So
it is free to use most advanced features of Joomla! 1.5.
My intention is to build extension, that is as much "natural",
native to Joomla, and that uses as much built-in (or existing) features
(tools, extensions...), as possible.
You may easily add transliteration functionality to your
extensions, just adding special trigger event for transliteration:
$StringToTransliterate = 'E.g. something in Russian: Это текст на русском языке';
$langTagOfStringContentLanguage = 'ru-RU';
$dispatcher =& JDispatcher::getInstance();
$dispatcher->trigger('onTransliterate_transliterate', array(&$StringToTransliterate, $langTagOfStringContentLanguage));
You may see full example in
'plugins/system/yvtransliterate/table_content/content.php' file.
Debugging mode of yvTransliterate allows you to see, what and how
was transliterated...
"Extend JLanguage class" option allows
yvTransliterate to add another 'hook' into Joomla! core. This feature
works MUCH more effective under PHP5 (it creates proxy to the JLanguage object instead of creating
(and populating...) second instance of JLanguage class (this is done for
PHP4).
History of changes
v.1.02 (December 06, 2009)
- yvTranliterate code moved to SVN repository, see Joomlacode.org
- Debugging was greately improved.
- 'Default content language' option was added. If the value of
this option was not selected, the language defaults to current Language
of User interface (as it was before this release).
v.1.01 (December 12, 2008)
- Added another 'hook' into Joomla! core: parameter 'Extend
JLanguage class'. Now yvTransliterate may transliterate not only
aliases of Articles (or comments in a case of yvComment), but aliases
of other elements of Joomla! site interface also: menu items, sections,
categories... in fact, yvTransliterate works in every place, where
Joomla! core calls JLanguage::transliterate method.
Please note, that in this case yvTransliterate uses Language of current
user as source Language for transliteration. So, for example, if you
want Section alias to be transliterated according to Russian
transliteration table, you have to log in to Administrator site
(backend) in Russian language.
This feature works MUCH more effective under PHP5 (it creates proxy to
the JLanguage object instead of creating (and populating...) second
instance of JLanguage class.
- Two new translations were added since previous release, see
them at JoomlaCode:
v.1.00 (July 17, 2008)
- First published version.
(c) 2007-2008 Yuri
Volkov, Moscow, Russia
