====== Translating phpList ======

Separate parts of phpList are translated independently:

  * The application web interface for administrators
  * Public-facing pages (for list subscribers)
  * Contextual help in the application
  * Contextual info in the application
  * The documentation website

===== Weblate (translate.phplist.org) =====

==== Application web interface for administrators ====

The strings are translated on the [[https://translate.phplist.org|translation website]]. This site runs [[https://weblate.org/en/|Weblate]] to provide a mechanism to allow translation of phpList by members of the phpList community.

How does this work:

  * The developers use special code that identifies the texts in the applications that are part of the language.
  * These texts are extracted from the code using [[http://www.poedit.net/|Poedit]].
  * The extraction of texts creates a [[http://en.wikipedia.org/wiki/Gettext|PO file]] which is added to the codebase. ((https://github.com/phpList/phplist3/blob/master/public_html/lists/admin/locale/en/phplist.po))
  * This template file is updated on the translation website every so often, so that updates in the texts are passed on to the translation system.
  * The translations are passed back into the source code.

Everyone can add suggestions on the translation site. Only selected administrators are allowed to approve the translations. If you are interested to become a moderator for your language, let the team know on [[https://discuss.phplist.org/c/translation-team/9|the Translation Channel]].


==== Access procedure for new Weblate translators ====

In order to help out translating, you need to do the following:

  * Sign up to the [[http://translate.phplist.org|Translation website]] and indicate your languages. 
  * Include "English" in your list of languages. (See below)
  * Post a message on the [[https://discuss.phplist.org/c/translation-team/9|the Translation Channel]]. 
  * Work your way through the translation until your language is 100%

The translation system has two modes for translations. One is to ''Suggest'' translations and the other one is to ''Save'' translations. Anyone (even when not logged in) can send suggestions, but only approved accounts can submit the translations.

Once you have made a few changes in the translations, you can go to the [[https://demo.phplist.com/lists/admin/| phpList Demo system]] and choose [[https://demo.phplist.org/lists/admin/?page=updatetranslation|"Update translations"]] from the menu, under "System" to see the changes. 

You can also try to [[develop/developmentsetup|run phpList on your local system]]

=== Why include English ===

If you include English as a language that you are interested in, you will see the actual texts that are used in the English language. This can at times be different from the "original word". For example, initially (20 years ago) phpList used "message" a lot but the terminology was changed to be "Campaign" instead, using the language system.

Also, as explained below, there are "system tags" that need translating, and that may be slightly obscure in the original text.

For example

   pagetitlehover:about

which in the English version of the translation is

   pagetitlehover:More information about the phpList application

So, in this case, you would need to translate the "More information about the phpList application" part, which is why you want to have the English language as a reference.  
   
   
==== Approve pending suggestions ====

When a new user account is created their rights level allows them only to suggest a translation on their language but not save it. For each language there are moderators who can approve the suggested translations and save them. To do so, you can visit a users profile and approve any suggested translations or go directly to a certain language and approve the strings that are translated by others. All the above can be performed only by approved accounts with moderator access. 


==== Weblate technical usage notes ====

There are a few things that you need to know when you start or edit a translation

  * **sprintf codes**. Some original language string can contain codes like '%d','%s' or '%0.2f'. These are texts where the %d is replaced in the code by some number. For more information read the [[http://php.net/sprintf|PHP documentation]]. 

It is essential that the translation has the same codes in it. Otherwise the text will disappear completely. So, for example
<code>
Processed %d out of %d messages
</code>

needs to have at least two times %d in your translation.

  * **Page titles**. The titles of pages, used in the main menu and the links to them, are taken from entries in the translation system that start with ''pagetitle:''. For example
<code>
pagetitle:dbcheck
</code>

You do not need to translate the "pagetitle:" bit, just the text after it. So, the example would be "Database check" as a translation. 

Note: Weblate only shows the msgid which is pagetitle:dbcheck. Please look for the English string in admin/locale/en/phplist.po which would give you "Verify the DB structure", and translate that string

  * **Page titles hover**. The hover text for the titles of pages, used in the main menu and links to pages. It is the text that will show when the mouse is held over the link without clicking. This can be more explanation of the page where you will go when you click. For example
<code>
pagetitlehover:dbcheck
</code>

You do not need to translate the "pagetitlehover:" bit, just the text after it. So, the example would be "Verify that the database structure is correct" as a possible translation. 

Note: Weblate only shows the msgid which is pagetitle:dbcheck. Please look for the English string in admin/locale/en/phplist.po which would give you "Verify that the current database structure is correct for the current version of the code", and translate that string.


  * **Terminology**. For each language, you can generate a Glossary. phpList in the past has been a little confusing about certain terms, and even the English "translation" is now different from the original. Please be aware of the current English terminology, regardless of the original string.

<code>
user -> Subscriber
message -> Campaign
email -> Either "email address" or "email message" (depends on the context)
</code>

and there may be similar words that require a clear definition. It is up to the language managers to determine this per language. Language specific rules for the translation are collected in the [[Notes on Translations]].

  * **Encoding**. All of phpList is in [[http://en.wikipedia.org/wiki/UTF-8|UTF-8]]. Regardless of anything you read in all kinds of places, use UTF-8 in your translations. There is no need to use HTML special characters, like &eacute;

  * **Updates**. phpList is continually updated and new texts will appear for translation. Changes are posted to the [[https://discuss.phplist.org/t/new-translations/7115|Translation Forums]] so that you can go back to keep your language up-to-date.

==== Adding a language ====

Adding a new language to phpList requires adding it to both phpList and the phpList application separately. Follow these steps:

  - Add the language in Weblate
    - Login to Weblate 
    - Scroll down at the list of languages and press the "Start new translation" button. Now you can select your language from a wide list of available languages. You should click again "Start new translation" and now your language will appear on the initial list of languages. 

  - Add the language to the phpList application
    - TBA

===== Translations managed by dedicated repositories =====

==== Public-facing pages ====

Public-facing pages such as subscribe pages, which do not require admin authentication to access, use a separate translation system. The strings are stored in .inc files in the following Git repository: https://github.com/phpList/phplist-lan-texts. These are a dependency of the lan-help repository. The phplist-lan-texts needs to be cloned into the ''%%texts%%'' directory within the ''%%/lists%%'' directory.

==== Contextual help in the application ====

Contextual help text is stored in a Git repository and not handled by Weblate: https://github.com/phpList/phplist-lan-help 

The files on this repo are used by the pop-up help buttons. When a new button is added the corresponding file should be added on this repo. Each button should have the parameter "topic" and the value must be equal to the name of the file that will popup when you click that button. Also the name of the file must be all lowercase.

To use contextual help text in a local development copy phpList, clone or download the above repository into the following directory of your phpList installation: <code>public_html/lists/admin/help</code>
Also make sure to have https://github.com/phpList/phplist-lan-texts cloned on your local installation, if not then there will be a dependency problem. 
 
Do not commit this folder to the phpList 3 repository (it should be ignored by git automatically thanks to .gitignore).

==== Contextual info in the application ====

Similar to help texts, these are stored in a dedicated repository, and should be checked out into the following folder: https://github.com/phpList/phplist-lan-info <code>public_html/lists/admin/info</code>
Do not commit this folder to the phpList 3 repository (it should be ignored by git automatically thanks to .gitignore).

===== Documentation =====

==== Resources wiki ====

To translate pages of this wiki, [[https://resources.phplist.com/translations/start?do=register|register an account]] and message the [[:discussion-lists|Translators Mailing list]] requesting to be made a moderator for your language. You can then add translations in your language directly.

==== Manual ====

Due to the software which created it being no longer maintained, the [[https://www.phplist.org/manual/|phpList manual]] is currently not translatable. If you'd like to help fix that, please contact us.

===== See also =====

[[Notes on Translations]] Language specific rules for the translation