====================
Tartube translations
====================

You want to contribute a translation to this project? Well, that's just great!

The simple way
--------------

Contributions can be made using Tartube's `Weblate page <https://hosted.weblate.org/projects/tartube/>`__, if that is convenient.

The not-so-simple way
---------------------

1. Get a copy of the file `../tartube/po/messages.pot <tartube/po/messages.pot>`__ 
2. Open it in a text editor
3. Read the notes below
4. Translate everything
5. Send the modified file to the authors, via `our GitHub page <https://github.com/axcore/tartube/issues>`__, and we'll take care of the rest

The technical way
-----------------

1. Fork the original `GitHub archive <https://github.com/axcore/tartube>`__
2. Clone the fork onto your system
3. Create a new directory/folder using the correct locale, in the form <ISO 639-1>_<ISO 3166-1 alpha-2>, e.g. **../tartube/locale/en_GB**, **../tartube/locale/es_ES**
4. Copy the file `../tartube/po/messages.pot <tartube/po/messages.pot>`__ into that directory, and rename it as **base.po**
5. Open the copy in a text editor
6. Read the notes below
7. Translate everything
8. Push the modified code back to your fork
9. Submit a pull request `here <https://github.com/axcore/tartube/pulls>`__.

Notes
-----

Header
======

The lines at the top must be changed from this::
    
    # SOME DESCRIPTIVE TITLE.
    # Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
    # This file is distributed under the same license as the PACKAGE package.

...to this::

    # Tartube
    # Copyright (C) 2019-2021 A S Lewis
    # This file is distributed under the same license as the Tartube package.

The Project-Id-Version must be changed from this::

    "Project-Id-Version: PACKAGE VERSION\n"

...to the current Tartube version, for example::

    "Project-Id-Version: 2.1\n"

The Language-Team field must be changed from this::

    "Language-Team: LANGUAGE <LL@li.org>\n"

...to this, again using the <ISO 639-1>_<ISO 3166-1 alpha-2> format, for example:

    "Language-Team: es_ES <EMAIL\@ADDRESS>\n"

The Content-Type field must be changed from this::

    "Content-Type: text/plain; charset=CHARSET\n"

...to this::

    "Content-Type: text/plain; charset=UTF-8\n"

Credits
=======

Change both of the following lines to claim credit. If you don't want to add an email address, then don't::

    # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
    "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"

For example::

    # FIRST AUTHOR Victor Hugo <victor@hugo.com>, 2020.
    "Last-Translator: Victor Hugo <victor@hugo.com>\n"

If you use an email address, it could also be added to the Language-Team field.

Translations
============

The rest of the document consists of pairs of strings. (A string is a single piece of text, enclosed within double quotes.)

The string labelled **msgid** is the original English text. The string labelled **msgstr** is an empty string that contains the translation.

For example, change this::

    msgid "Channel"
    msgstr ""

...to this::

    msgid "Channel"
    msgstr "Canal"

If you don't add a translation, then the original English is used. (This can be useful for words which are the same in both languages.)

Some pieces of text are spread across several lines, like this::

    msgid ""
    "The video file is missing from Tartube's data folder (try downloading the "
    "video again!)"    
    msgstr ""

The two strings are added to each other, producing a single string. You can do the same, if you want. (It doesn't matter how many strings you use).

Multiple strings are combined without extra space characters. You should add them yourself, as in the example below::

    msgid ""
    "The video file is missing from Tartube's data folder (try downloading the "
    "video again!)"
    msgstr ""
    "¡No puedo usar "
    "YouTube "
    "porque no hablo inglés!"
    
Please preserve capitalisation and punctuation::

    msgid "Help!"
    msgstr "¡Ayuda!"

    msgid "HELP!"
    msgstr "¡AYUDA!"
    
    msgid "help!"
    msgstr "¡ayuda!"
    
One exception to this rule is underline/underscore characters. These denote keyboard shortcuts. Don't add the underline/underscore character to your translation::

    msgid "_Channel"
    msgstr "Canal"

Comments
========

Sometimes the programme that generates the **messages.pot** file adds extra comments. You can ignore any line that starts with a # character. These lines were generated by a computer, not by a human.

Clarifications
==============

We've added a few clarifications to help you, for example this one::

    msgid "TRANSLATOR'S NOTE: Ext is short for a file extension, e.g. .EXE"
    msgstr ""

You don't need to translate the clarification. Nothing uses it and no-one will see it.

If you're not sure how something should be translated, let's discuss it on `our GitHub page <https://github.com/axcore/tartube/issues>`__.

Substitutions
=============

Some strings contain {0}, {1}, {2} and so on. These are substituted for something else.

    msgid "Give the {0} to the {1}, please"

Your translation must include the literal {0}, {1}, {2} and so on.

    msgstr "blah blah blah {0} blah blah {1} blah blah"
    
If your translation uses a different word order, then treat the substrings like a word.

    msgstr "Give to the {1} the {0}, please"

Directories/folders
===================

Earlier version of Tartube used *directory* on Linux systems, and *folder* on MS Windows. To make translations simpler, we have removed this distinction. Everything is not a *folder*.

Downloads
=========

You have probably noticed two buttons in Tartube's main window: **Check all** and **Download all**. 

The first one fetches a list of videos from websites, but doesn't download the videos. The second one fetches a list of videos from websites AND downloads the videos.

Throughout **messages.pot**, the word *check* is used with this meaning. You can decided for yourself how to translate it.

Operations
==========

Throughout **messages.pot**, the word *operation* has a fixed meaning. When Tartube is busy doing something, many buttons don't work (are greyed out). 

For example, click the **Download all** button, and it is greyed out until the downloads are finished.

There are five operations. You can decide for yourself, the best way to translate them.

**Download operation**: downloads videos, or just fetches a list of videos. The **Check all** and **Download all** buttons both start a **download operation**

**Update operation**: installs FFmpeg, or installs youtube-dl, or updates youtube-dl to the latest version

**Refresh operation**: searches a directory/folder on the user's filesystem. If videos are found, those videos are added to Tartube's database

**Info operation**: fetches a list of the available video/audio formats for a video, or fetches a list of available subtitles for a video. Also used to test youtube-dl

**Tidy operation**: tidies up the directory/folder where Tartube stores its videos. Checks that fils are not missing, not corrupted, and so on
