Users' guide

Settings (shortcut key "S")

First it is recomended to set up the programm. Click on "Settings" (shortcut key "s"). Set the language you want to translate to. Set also the name and e-mail of translator. It will be used only to be included in translated files, to let know further translators who did the translations before.

do not show plugins without translate file - some plugins, especially templates, have no language files, no messages to translate. In the list of plugins, they are only for your information. Checking this option will hide them in the list.

Style of line breaks lets you choose, which characters will be used as end of line.

WWW address with application - Here you can specify our own server (folder) that holds newest version of application.

Serendipity core, Additional plugins, Additional themes - Here you can set the access method (Repository type) and addres of remote repository (URL), from which the lang files are downloaded, and where to store them on your computer (Local folder). Default settings work well, in first it is not necessary to change it. If you observe difficulties, eg. downloading seem to be slow, you can try to change it. But you shoud read paragraph about protocols first.

Button Reset to default settings will set defaults for remote type and URLs for all three repositories.

Main window

"Update plugin list" button (shortcut key "U")

After clicking, the application will connect to the internet repository (the same as Spartacus uses), download the list of plugins and will try to know, which plugin includes translated language files. In this moment the application does not know the content of language files. It only knows, that some translated file exists. To prospect language files it is necessary to download them by clicking on following button.

In version 2.1, the native git protocol was fully implemented. This protocol needs to update of whole repository before it can know the list of plugins. It means that for git native protocol, the buttons "Update plugin list" and "Download files" do the same thing. The progress of acquiring list of plugins is now displayed in status bar.

"Download files" button (shortcut key "D")

The program will download language files - english files and also the files in selected local language (see Settings) and will compare them by content. Downloading can be lengthy, therefore there is bar that informs you about the downloading progress in status bar.

In version 1.6 was added feature, that downloads only changed files. Downloading is now a bit faster. Also you can now stop the downloading by bancel button. Since mentioned version, documentation files (documentation_xx.html, readmes, ChangeLogs) are also downloaded to enable you to translate also this documentation. See section Documentation translations.

"Compare files by content" button (shortcut key "C")

If there comes up a situation when files are not compared (e.g. after you translate documentation files), you can force the comparison by clicking this button. The programm compares locally stored files, nothing is downloaded from internet.

With all the features added along the time, the compare operation got a little bit complicated and lengthy. Its progress is displayed in status bar.

Status bar

All posibly lengthy operations are now observed and their progress is displayed here, on the bottom of main window. If you do not want to wait for the finish of operation, you can stop it by clicking the button Cancel.

If no lengthy operation is running, the status bare hides automatically.

Plugin table

• double-click on the row, or select the row and press "enter" - will open translation window
• Right-click on the row will display info about plugin and list of files used during translations.
• "Type" column:
  1. system - system file, the core language file that serendipity uses
  2. event - language file for event plugin
  3. sidebar - language file for sidebar plugin
  4. template - language file for template
• "Internal" column - checked plugins are part of serendipity distribution, others are available through web or Spartacus
• "en" column and "loc" column - number of language constants (rows) in english (local) language file. Looking this you can choose if you want to translate big plugins with lots of rows, or you can choose some small plugin if you don't have much time to translate big file. You can also know, how many messages are in partially translated file and how many of them it is necesary to translate.
• "Status" column and "Translate status" column:
  1. ok - all messages from english file are present in local language file, this file is completely translated. Also the number in "en" column is the same as the number in "loc" column.
  2. no - local language file does not exist. It is possible to translate (create) it.
  3. partial - some of the messages in english file are present in local language file. It means the number in "en" column does not match the number in "loc" column. Some of the messages must be translated or deleted.
  4. problem - the plugin does not have any english language file. There is nothing to translate.

  "Status" column compares downloaded file (from "plugins" directory) with english one.

  "Translate status" column compares translated file (from "plugins_translated" directory) with english one.

  These situations are possible.
  1. If one plugin has "Status" partial or no, and "translate status" is ok, then we have already translated the file, but it wasn't uploaded to the internet repository. It is time to publish it on serendipity forum.
  2. "Status" is ok, "Translate status" is no - it means that the plugin is well translated, but we didn't do the translation. There is no need to translate it any more.
  3. "Status" is partial or no and "Translate status" is partial. It means that we have alredy translated the file, but that we didn't finish the job. It needs to finish the translation and to publish the result on serendipity forum.
• "Documentation" column: Displays status of translation of documentation, which can be following:
  1. ok - Documentation file in local (e.g. czech) language downloaded from server is younger than english documentation file, therefore it can be supposed that this translation is complete and up to date.
  2. local - Documentation file in local (e.g. czech) does not exist on server, but exists on local computer and is younger than english documentation file. It means that you did the translation, which is still up to date, but you did not publish the translation to the world.
  3. no - English documentation file exist, but file in local language does not. It is time to translate this documentation.
  4. partial - Both english and local language documentation files were found on server and downloaded, but the local language documentation is older than english one. Or english file exist, translation exist on local computer, but it is older than english file. It means that english documentation was renewed and these changes were not reflected in local language documentation.
  5. problem - The plugin does not have english documentation, there is nothing to translate.

Translation window

In the upper part of translation window, there are three fields - the name of edited message, the message in english and the message in local language.

Local language messages can be edited in the table with messages and also in the field with local message.

In the status bar, there is "original" x "modified" message. It signalises if the file has been changed or not. If the status is "modified", it is possible to save the file. The file will be stored in "plugins_translated" directory.

• red - the message is not translated in local language
• green - the message exists in local language, but it is the same as in the english language file. It is highly probable, that the translator who translated the file before you, did the copy of messages, but did not translate all of them.
• yellow - the message exists in local language, but not in english. It is possible that it was removed in newer version of plugin. If we want to remove it from the translated file, we will delete it. Blank messages are not written in the language file during saving.
• white - the message exists both in english and local language file and they are different. It means translated message. Completely translated files contain only white and green messages. Sometimes the translation is the same as the english message.

Translation of documentation

Documentation for plugins can be stored in various files. It should be placed in file named "documentation_en.html", but many plugins have only readmes "readme, readme.txt, pluginReadme.txt, credits.txt" or ChangeLogs instead. All of these files are downloaded and treated as documentation files.

As the format of documentation files varies a lot, you must inspect it on our own and make its translation in external text editor.

If you want to profit from benefits of tracking the status of documentation and of packing new files for publishing, you should only save your translated documentation under the plugin folder in "plugins_translated" directory and save it as "documentation_xx.html" where replace "xx" by language abbreviation.

From version 1.9 the application creates automatically the UTF-8 version of documentation files, if it does not exist. However it has limitations. The UTF-8 files can be different in small things. The application converts the html meta tag defining the charset to utf-8, to display the documentation file correctly in utf-8 encoding. Also the links to local files (e.g. images) are prefixed with "../" co link to original file. Remote links (starting with "http://" or "mailto:") are not prefixed. All other changes in utf-8 files must be done manually.

The documentation files in utf-8 encoding are created after clicking on "export translated files to zip file" in "translations" menu.

Protocols - access to internet repositories

ATTENTION! URL address of internet repository is bound with type of repository - eg. github.com has its git html web page, sourceforge.net offers its web frontend for cvs. Serendipity Translator does not check this dependencies, so you can make it not working, when you set it wrong, eg. when you write github.com in URL field and select cvs repository.

• HTML protocols - svn, cvs - It's easy, these protocols connect to www interface of repository (the same way you can watch them in your internet browser), read its content, parse it and gets the information about plugins and files. These protocols download all files changed from last download. Than the app works with downloaded files.
• git html (deprecated) - It is regular html protocol, that connects to web page of gitHub and tries to parse the html page. But at gitHub there are issues, that make the use of this protocol uncomfortable. The html frontend of github is filled with javascript, which Serendipity Translator cannot pass. For example the information about last modified date known to SerendipityTranslator only in special cases. It causes, that all files are almost always downloaded (more net traffic and more time), and that documentation cannot display properly its status (translated, not translated). Therefore I recommend to use default "git native" protocol. See below.
• folder - Ignores the remote URL settings. Just reads the files from local directory. Does not download anything. It is necessary to update the files outside Serendipity Translator. The date is red form the file's last modified date. It is reason, why next scenario does not work well: to set externally git or cvs file, update it externally and access it through Serendipity Translator "folder" protocol. Because the files updated through git (cvs) do not have the date equivalent to the date of last commit, when they were modified.
• git native - benefits from versioning system git. From version 2.1 it can set up local repository and connect it to remote repository (eg. github) given in remote URL settings. The URL is used only to initial linking of local repository to remote one. If you want to update local repository from different remote repository, you must delete whole local directory with git repository and re-create it with new URL. Serendipity Translator gets the file date not from last-modified property, but from the date of last commit in git, when the file was modified.

How the program works internally

Filling in messages already set elsewhere

• In some plugins, especially templates there are some messages that are repeated (copied) from other plugins (mostly templates) frequently. The application stores all messages into its internal database during each comparison. And then if it finds untranslated message whose key is already in database, it fills in the translated message. This supports also the coherency of translation. There is less chance to translate logically the same messages differently.

Directories it creates

• plugins - directory with downloaded language files. These files change only after clicking the "Download files" button and downloading the up to date files. It contains the same language files that are available in online plugins repository.
• plugins_translated - There is the result of your translation effort. The publishing of translated files is not automatic. It is up to you to publish them, mainly on serendipity forum (board.s9y.org). The plugins are sorted in subdirectories in groups, that are important for serendipity developpers.

Language file format

• header - it is automatically generated, it contains the information about translation version, translator name (it is taken from Settings dialogue) and date of translation
• The file that is created from the scratch, the first version of the translation, has the messages sorted in the same order as in the english file.
• The file, that was already translated, it means when we make only the update of the file, has the same ordering of messages as the original file. The parts that are not changed, have the same format in both files. New messages are appended at the end of the file. The program tries to preserve the format of messages. It means mainly the caracters between the message name and its content in @define function. So when the main part of language file has the format "@define('BLABLAH',[tab]'blahblah message');" also the new messages will have ",[tab]" in the right place. Also the padding to some position is supported, e.g. if 'blahblah message' starts mostly on column 50, the new messages will start also on column 50.

Syntax check of translated files

If you have php installed (it means when it is accessible through typing "php -l filename.php" through command line), then all files are passed to this external php parser to check the syntax. So you are warned always, when you make non-valid php code, that could potentially shutdown whole blog.

Export to zip file

• Only plugins that are completely translated are exported into zip file. It means that "Translated status" equals to "ok", and plugin is not translated yet, it means when "Status" is not "ok" or if messages in translated file are not the same as messages in downloaded file.
• Only files of current language are exported.
• Documentation files of current language are exported only if documentation status equals "local".
• Files are exported both in local encoding and in UTF-8 encoding.
• Files are organized in one zip archive in subdirectories according to their type - internal x external, plugins x templates.

Troubleshooting

• All error messages are in file "error.log"
• If you encounter any problem, send this error log to author of translation utility.

Changelog

• 1.0
  Prerelease version - the main function were tested (plugin list downloading, basic translations)
• 1.1
  More info about translations was added (e.g. number of messages in translated file), graphical enhancement (the state of messages - translated/not translated)
• 1.2
  Changes in user interface (menu bar, settings in its proper dialogue, dialogue "about", license dialogue, help dialogue), formating of output file (e.g. resolving the new messages format)
• 1.3
  Resolving plugin list from web interface of snv/cvs repository. Export of translated files into zip archive. Statistics added.
• 1.4
  Added comparing of files after plugin list update. Reporting error messages into file added.
• 1.5
  Fixed errors with (not)downloading some files. Added filling in the messages that were already used in other plugins (templates).
• 1.6
  Added tracking of documentation files.
  Added automatic updater of application.
  Added function of downloading changed/new files only -> performance enhamncement.
  Added possibility of cancelation of downloading.
• 1.7
  Fixed error in (not)downloading documentation files. Download dialog - saving its position + visibility enhancement.
• 1.8
  Added check of availability of cvs/svn servers. Error message is displayed if they are not reachable.
• 1.9 - 2011/07/10
  Fix to download also the files that are old only several seconds.
  Fix of exporting files that have identical content, but differ in new line style (\n - unix style or \r\n - windows style). They are now supposed to be identic.
  Saving of downloaded files with original timestamp - this avoids false marking of documentation files as not translated.
  Added automatic conversion of documentation files into UTF-8 version.
• 2.0 - 2011/12/10
  Added - now also files "todo", "copy*", "author(s)" are downloaded as documentation.
  Added - The "Settings" dialogue was extended. Now it is possible to set the internet repository, from which language files will be downloaded.
  Added - support of git.
  Added - function to update the application. A library is used to access the git, so now the application has more than one file. It is necessarry to download all files in one zip file and then to unpack it.
• 2.1 - 2012/01/07
  Added - possibility to reset settings to default values
  Modified - all default settings changed to point to gihub using native git protocol.
  Improved - downloading by native git protocol. Now fully usable - it can set up new git repository, download it from remote, also it can announce well the progress of update.
  Modified - the progress dialog was removed, the progress bar was integrated in main window and now displays also the progress of reading list of plugins and progress of comparing operation.
  Improved - git html protocol. Now it downloads the latest commit. Nevertheless it is recomended to use default setting and to access the gitHub via native git protocol.
  Modified - the bundled jgit library was updated to recent version.
• 2.2 - 2012/02/18
  Fixed - wrong classification of plugins (core/extern; plugin/template)
  Fixed - wrong directories in export to zip file
  Added - splash screen on startup
  Added - check of php syntax using external php parser
  Added - display info about plugin and its filelist after right click on row of plugin in plugin window
  Added - posibility to select style of linebreaks
• 2.3 - 2013/12/31
  Added - icon
  Fixed - untracked exception when parsing version and subversion of language file
  Fixed - git pull fail when connecting to git server using ssh with key protected by password - now app asks for this password
  Modified - structure of lang file does not contain CVS tags any more (because git is used for longer time as repository)