Background
I have designed a project using smarty and I have decided that the easiest way to add a transaltion system was to use gettext() because it was widely supported. I shortly discovered there were many issues with it which I have resolved bar one, scanning smarty .tpl files with Poedit. I am not going to do all my translations manually!!!
I managed to get quite far using poedit and messing with the various parsers but they were not 100% for me.
The goto plugin for smarty to add gettext support is smarty-gettext , a plugin that allows you to put text you want to translate inbetween some custom tags and then these will be translated into gettext() statements.
{t}....{/t}
Now Poedit will not find these tags, nor can you config custom scans for it in the software. You can however use external extrators to do this.
smarty-gettext has a command line parser that will scan your .tpl files and return correctly formatted .po and .mo files but this means you have to scan from the command line with this script, then you have to use Poedit to scan your PHP files which could get quite messy and then somehow merge the 2. So to that end I have manged to get the command line parser to function as a Poedit extractor. I will also go through the different parts of the process so you can perhaps build your own parser or utilise one that is already there. I have also found a few other Poedit parsers that might be of use and i will also list them later.
These instructions were written with gettext() in mind but because of caching issues with gettext() I decided to use motranslate. The instructions are exactly the same for both technologies except you need to add some Additional keywords for motranslate.
The Process
My advise is to follow these instructions carefully and then once you have the process working it is at that point you should alter it to your needs. These instructions are also for Windows and Xampp.
I will be using my file locations so everything matches up. I will also assume
Prerequisites
- Poedit 1.83 - The newer version is not as easy to use and I would not recommend it.
- Xampp v5.6.30 - I use the zip version because it is easier.
- Windows
- gettext 0.19.8.1 and iconv 1.14 - Binaries for Windows (static) - I used 64bit but 32bit should be ok aswell
- smarty-gettext (block.t.php, function.php so smarty will translate and tsmarty2c.php for the parser) - just copy raw version into a text file with the correct name.
- the gettext() translation system is setup in your project
- Smarty plugins are installed (block.t.php, function.php).
- You also will need a couple of {t}....{/t} strings to exisit so they can be found.
Edit tsmarty2c.php to search .js files
When specifying a directory the script will only search within .tpl files and I need it to search with some .js files I have in my project. So edit the file and change:
// extensions of smarty files, used when going through a directory
$extensions = array('tpl');
to
// extensions of smarty files, used when going through a directory
$extensions = array('tpl', 'js');
Configure the enviroment
- install xampp to D:\websites
- install Poedit
- create a folder D:\websites\php\gettext
- Extract msgcat.exe and msgmerge.exe from gettext 0.19.8.1 and iconv 1.14 - Binaries for Windows (static) and put them in D:\websites\php\gettext
- Put a copy of tsmarty2c.php into D:\websites\php\gettext
- add the 2 following paths to you windows PATH variable
- D:\websites\php
- D:\websites\php\gettext.
- restart windows so the new paths will be recognised
- I added the 2 folders to the windows PATH so the files within can be found easily. You can probably get all of this working without adding stuff to the PATH but I would not reommend it. php.exe, msgcat.exe and msgmerge.exe all need to be found for this to work.
- You could probably get away with just adding the D:\websites\php tot he PATH but I found it neater to have these other files in their own folder.
- I choose the static versions for the gettext() package so I did not have to worry about if the .dll files were registered or could be found
- xammp does not need to be running
- make sure you do not have other version of gettext in the path otherwise the software can get confused
Configure Poedit
All the files and settings are inplace we now need to configure Poedit. Make sure you download the older v1.8.13 version because you can still see how all of the parsers are configured.
On the orginal Poedit (v1.8) you were able to select which parsers were enabled. These were all configured the same except for the language type and what files they scanned. In v2.0 this has been removed. Below is the PHP Extractor setupfrom v1.8.
I have been using Poedit v2 with success for QWcrm.
Instructions
- Open Poedit v1.8
- Open up your primary language .po file D:\websites\htdocs\develop\qwcrm\language\en_GB\LC_MESSAGES\site.mo
- Goto Catalogue->Properties->Source paths
- and configure your folders as required for your project.
- Dont forget you probably will have PHP and TPL sections. You can scan the whole project if you want.
- Goto File->Preferences->Extractors
- Disable all extractors you dont need - This makes experimenting easier but is optional. I just kept PHP
- Create a new extractor with these settings
- Language: Smarty
- List of extensions: *.tpl;*.js
- and any other files types that use smarty and need translating.
- Command to extract translations:
Search all folders supplied by Poedit (recommended) php "D:\websites\php\tsmarty2c.php" -o %o %F Only searches in the folder 'themes' php "D:\websites\php\tsmarty2c.php" -o %o themes
- An item in keywords list: -k%k
- An item in input files list: %f
- Source code charset: nothing in this
- Looks like this for my example
- Edit the Catalogue Properties - Will not appear until you have created a new catalogue and I have used QWcrm as an example. These settings are stored in the .po file.
- Translation properties
- Project name and version - QWcrm v3.0.0
- Language team - https://quantumwarp.com/
- Language - English (United Kingdom) - set this to the language of the translation you are doing.
- Plural forms - leave as 'Use default rules for this language' unbless you know why you want to change this.
- Charset - UTF-8 (recommended)
- Source code charset - UTF-8 (recommended)
- Source Paths
- Base path - This should be the root folder of your project.
D:\websites\htdocs\develop\qwcrm
- Paths - . (only a period)
- Excluded paths - This is important to reduce the files that are scanned such as cached files which also have gettext() functions in them. These are my exclusions, yours will be different.
cache\ nbproject\ libraries\ logs\ media\ themes\default\js\dhtmlcombo\ themes\default\js\tinymce\ themes\default\js\jscal2\jscal2.js themes\default\js\jscal2\unicode-letter.js themes\default\js\jscal2\css\
- Base path - This should be the root folder of your project.
- Sources keywords
- Additional keywords - These are only required if you are using motranslate.
_gettext - This is for the function _gettext() __ - This is for the function __()
- Additional keywords - These are only required if you are using motranslate.
- Translation properties
NB:
- I could not get %f to work with this process and so I had to use the folder name themes. Not exactly sure if Poedit is adding the rest of the file location onto it.
- You must use %F in your extractor string i.e. uppercase.
- themes is my root folder that is holding all of my .tpl files
- you will notcie that i have added *.js and this is because I have some files that are *.js with some smarty tags in that need parsing.
- when using this extrator the files you configure in the catalogue (i.e. include excludes) will be ignores because you are not using the %f option. I would like to get this fixed so i can use it.
- because we are not using %F for the file list and instead a hardcode value we will need to change the target directory for each project for the Smarty Extractor. You could create multiple extractors and just keep them disabled until you need them.
- Also when you are not using the particular smarty extractor you will need to disable it as it will always search that directory.
- If there are not translations found by the smarty extractor then Poedit will generate and error saying thas the .po file might be corrupt. This might also be the case of all extractors but I cannot be 100% because i am not going to spend time testing that hunch.
- Poedit does not always save you preferences and settings so make sure you save and check them if things are not working.
- in Poedit a folder 'Exclusion' will override a folder 'Inclusion'.
I will just explain a little here about this extraction process. All of the other Extractors are using xgettext() to scan files and return a correctly formatted .po file. xgettext() is dated and will not recognise a lot of languages and you can not add custom scans in to it.
Poedit extractor switches explained (This is useful so you can workout how to build you own parser.)
- -o - This is just a standard switch that is pass to the extractor. It is not specific to Poedit. However the xgettext() uses this to denote the output file and so does tsmarty2c.php
- %o - this is a placeholder for Poedit to swap out with the tempory .pot file location where changes are merged to.
- %k - this placeholder is to be able to pass custom function names to your script (or xgettext) to scan within for strings i.e. instead of gettext("translate me") you could scan for chicken("translate me") or football("translate me"). It is not mandatory to have this.
- %f - this is placeholder for the file list. I am not sure of the format but it is in a format that ngettext() will accept. All files are passed in 1 large list here. I can't work out if this is type, but to pass the list you need to use %F.
- --from-code=%c - this is always added on to the end of the command line and is to specify what charset the files houls be open as. I do not need this so have removed it. I thing it is mainly for xgettext. My scripts have been running with it attached though.
- NB: the instructions for Poedit for the extractors does not make sense. There is information left out.
So what happens with an extractor when you hit 'update from sources'
- poedit scans the project's folders (as per your rules) for allowed files and builds a list
- one of the following happens (not sure which)
- The files are passed as a single command line to an extractor that matches the file extensions (possible goes to multiple extractors if an extension is registered in more than 1 extractor)
- Each file is passed as a single command line to an extractor that matches the file extension (possible goes to multiple extractors if an extension is registered in more than 1 extractor)
- the extractor then parses these files and then merges the strings it finds to a temporary pot.file (using msgmerge.exe)
- the next extractor is run and those files are merged into the same temporary .pot file(using msgmerge.exe)
- once finished Poedit loads this temporary .pot file in to memory and you are returned to the main screen
- your changes have not been saved yet. For this you actually need to hit save to apply the changes to you .po file.
- Poedit will now build the .po and .mo files
Extract the Translations
Comodo Sandbox which is part of the comodo Internet Security (CIS) if running will cause the extraction process to fail because it blocks the PHP script. You need to disable the Comodo Sandbox before running the extraction. This might also be the case for other sandboxes and Firewalls.
So now run Poedit and extract the translations as outlined above by hitting the Update from sources menu item of click the Update button.