Translate_Into_A_New_Language
You need three things to translate Panopticon:
- [Poedit]Poedit, a free of charge, cross-platform, open source translation software.
- A plain text editor such as Notepad (Windows), Notepad++ (Windows), BBedit (macOS), gEdit (Linux / GNOME), Kate (Linux / KDE) or similar. Don't worry, this is just to copy file contents around.
- A GitHub account, to submit your work.
You can download and install Poedit on Windows, macOS, and Linux from its site. Linux users should best use the Snap package provided on Poedit's site, or compile their own, instead of using the package included with their distribution. The version of Poedit packaged with most distributions still works fine, but it's outdated, and some features described herein might not apply.
Before you start translating Panopticon, you need to download the translation file template (POT) from its GitHub repository. On the toolbar, towards the right hand side, there's a download button (to the left of the pencil icon).
You need to rename this file to the language code you're translating in, and the extension .po (instead .pot). The naming of languages is explained in the File Structure page. If you come from the Joomla! world you'll immediately recognise the convention used, e.g. de-DE for German (Germany) and de-AT for German (Austria). If you come from the WordPress world, remember that the language name is followed by a dash and the two-letter ISO country code.
So, let's say you want to translate to Canadian French. You will have to rename panopticon.pot to fr-CA.po.
To open a translation for editing, open Poedit and click on Browse Files.
Select your PO file (in this example, I selected el-GR.po for the Greek language) and click on Open. You will then see the translation interface.
The very first time you open Poedit you have to change a few of its configuration options. Remember to open your PO file first, otherwise you do not see the necessary menu item!
Go to the Edit, Preferences menu item.
In the General tab enter the following.
- Name: your full name
- Email: your email address
- Check spelling: checked
In the Advanced tab select the following.
- Line endings: UNIX (recommended)
- Preserve formatting for existing files: checked
Click on OK.
This ensures that when you save your translation source file nothing will be broken.
ℹ️ This feature is available since Panopticon 1.0.6
In your Panopticon installation create the file user_code/bootstrap.php with the following contents:
<?php
\Akeeba\Panopticon\Helper\LanguageTools::convertAllToIni();Then, upload your language's PO file into your Panopticon installation's languages folder.
Panopticon will automatically convert the PO file into an INI file, which means that you can use it with your Panopticon installation.
After you are done translating you will have a new PO file. You need to submit that file to the Panopticon repository for the bundled language files to be updated. This is done by creating Pull Requests.
❗ Do NOT submit a new discussion or issue with your new PO file, or comment to an existing one attaching or linking to your new file. The only acceptable way to submit your translation is through a Pull Request. This is important for maintaining a correlation of who changed what in Panopticon, including its languages. This becomes extremely important when someone disagrees with a translation string. Such disputes can only be resolved by notifying the person who submitted the translation, and the only way to do that is to have the correlation between change and person making it through the acceptance of Pull Requests.
It may sound daunting, but there's a reason we chose to host our code on GitHub. It makes it fairly simple for non-developers to submit Pull Requests which contain just a single new file.
First, log into GitHub and go to the languages folder inside Panopticon's repository.
From the top part of the page click on Add file, Create New File.
If you have never done this before GitHub will tell you that you need to “fork” the repository.
Don't worry! Just click on the bright green Fork this repository button. Magic takes place in the background.
Fill in the name of your file. It's the same filename you created, e.g. fr-CA.po for Canadian French.
Copy all the file contents into your clipboard. How? On Windows and Linux, click anywhere inside the text and press CTRL-A followed by CTRL-C. On macOS, click anywhere inside the text and press CMD-A followed by CMD-C.
Back to your browser, click inside the editor, then select and delete all the text (CTRL-A followed by BACKSPACE on Windows and Linux, CMD-A followed by DELETE on macOS). Then, paste the contents of your clipboard (CTRL-V on Windows and Linux, CMD-V on macOS).
Give it a quick glance over to make sure you have pasted the right text. Then, click on the green “Commit changes...” button above the editor.
You will see a message box where you can enter some optional information. You don't need to change anything. Just click on “Sign off and propose changes”.
That's it! You have submitted a pull request to the Panopticon project with the new language file. The developers will merge it within a couple of days, and update the INI files a few minutes to hours later.
To update your translation you will be following a similar process.
As noted above, the only acceptable method for submitting translations is through a Pull Request. Please do not start a new discussion or issue, or comment on an existing discussion or issue with a copy or link to your new translation. Do not submit issues or discussions with new language strings, either. These methods will NOT result in the translation being created and will be replied to with a link to this page. As explained, the reason for the Pull Requests is that they maintain correlation between the translation and the translator. This is very important when there is a dispute about the best way to translate something in a language we don't speak and don't manage.
We understand that nobody has infinite time to do a full translation from start to finish in one sitting. You will need to take breaks, and come back to it whenever you have more time. Please do not submit a translation source file if you know you are going to be translating some more in the next 3–4 business days. By the time we accept your Pull Request you'll be coming with a new one, which at best is unnecessary work, and at worst it can cause even more work resolving merge conflicts.
Do not submit INI files directly. The only acceptable exception is if it's a new file, and you have cleared that with us. We will need to merge your translation INI file, then convert it to a PO file, and update the repository. This takes a bit of extra time, hence the need to clear it with us first to avoid that additional work coming to us at an inopportune moment.
Do not just pass all strings through a machine translator software / service such as Google Translate, DeepL, etc. The quality of machine translations is rarely acceptable for short strings like software translation files. Users detected doing this will be banned from the Panopticon repository. It is, however, okay to use machine translation to get to a good starting point AS LONG AS you proofread and edit every single language string. If there are strings you have not had the time to proofread yet, please remove them from your translation. A bad translation is worse than no translation at all.
Aside: Back in the Joomla! 1.0 days (2005-2007) an unfortunate misunderstanding led to the english string “FTP Directory” to be translated to the equivalent of “FTP company manager”. Most users had no idea what that was and left it empty. As a result, Joomla! was perceived to be broken among Greek users of cheap hosting on which Joomla! required the FTP layer to be set up to work correctly. It took years for people to figure out that this was the reason. Someone confusing "directory" with "director" was enough for a CMS to get a bad reputation in two countries (Greek and Cyprus), leading hordes of users to WordPress instead. So, yes, a bad translation is worse than no translation at all!
Finally, please mind your tone of voice, grammar, and spelling.
Panopticon's tone of voice is casual office. It's neither formal, nor colloquial. You should translate strings using the same tone of voice you'd be using to talk to your higher-up in an office environment. You should use neither the formulaic speech of academia and boardroom, nor the informal speech used with your friends. And, for the love of Cthulhu, don't try to be prosaic when clarity will do just fine.
In languages which use the second plural person to convey respect when talking to someone (e.g. “Sie” in German, “vous” in French, “εσείς” in Greek), whereas the second singular person conveys familiarity (e.g. “du” in German, “tu” in French, “εσύ” in Greek) you should always use the second plural person. If your culture does not use this convention, as is common in most of Scandinavian countries (at least that's what reading Scandinavian crime thrillers led me to believe), you should use whichever sounds more natural to you, but please be consistent.
When translating computer-related terms, please exercise your best judgement whether your country's people are more likely to understand the translated or the English term. For example, “email” is usually understood better untranslated, except in France where the translated term “couriel” is far more likely to be understood. Sometimes you may have to use colloquial terms for people to understand what you mean. For example, the term "at-sign" (referring to the character @) should never be translated in Greek as “σύμβολο του προς” because nobody understands what it is. Instead, it would have to be translated as “παπάκι” (literally: little duckling) which is the colloquial term for the sign that everyone understands.