path: root/README

see separate NEWS file

FEATURES
-it's very configurable
-support for git (currently all resources except translations for web pages)
-support for many types of svn checkout: anonymous (default), user or ssh key authentication
-support for doc team resources
-it logs all important actions
-it operates on list of translatable resources in git (including web pages)
-automatic update of list of translatable resources
-git and svn clone/checkout or pull/update as needed on every single resource
-create and show a list of resources with untranslated and fuzzy strings with statistics (numbers of translated, fuzzy and untranslated strings)
-checking the syntax of po file from git if required
-checking the syntax of pot file from git if required
-copying the *.pot file, *.po file, *.desktop file, *.html and web page files for editing in working directory if required
-creation of working copy of po resource in working directory if required
-testing for differences of *.po file from working copy if required
-testing for differences of *.pot file from working copy if required
-option to exclude all work on web pages translation
-checking and addition of git configuration
-searching for new *.pot files in svn (TODO also search from git)


INSTALLATION AND CONFIGURATION
It's recommended to put the script check_for_translation_work.sh in the root of your git directory. There it will automatically update itself by default.
You must make it executable by giving it permission to execute. It's also recommended that you create a symlink in your home directory ~/bin to the script. 
That way it will be in your PATH so you can call it from any directory.
After first run please adjust file ~/.mageia-i18n-config to suit your needs.
Script will automatically copy or update list of translatable resources if check_updates is set to 1 (default) in config file.
If you choose to disable update you should manually copy list (translation_projects.dat) to the location of git_directory in config file.

Remember to upload your public ssh key to mageia identity! Otherwise the script will prompt you for password every time for every svn resource and
git commit & push will be unavailable to you.
See wiki (https://wiki.mageia.org/en/Git_usage_for_l10n_and_doc) for details.
It's recommended that you first try git clone and push without script to test if your setup of ssh and git is as it should be.
Same goes for svn commit if you need it (currently there are only translations for web pages left on svn).
You can exclude all work on web pages translation with option work_on_web_pages_translation. In that case you don't need to configure svn at all.

At least you need to adjust following setings in configuration file named .mageia-i18n-config that has been made in your home directory on the first run
of the script.

Set this according to your language code:
language_code=sl

Adjust svn, git and working translations directories
svn_directory= default is just a template: /home/user/Mageia/i18n/svn
git_directory="/home/user/Mageia/i18n/git" # added after git transition
working_translations_directory= default is /home/user/Mageia/i18n/translations

choose anonymous svn method if you don't need commit access:
svn_method="svn://"

otherwise choose public ssh key svn access:
svn_method="svn+ssh://"

Other options should be obvious by its name or comment.


USAGE OF THE SCRIPT
First time after your configuration the script will need some time to clone all the needed git repos. Just wait a bit. It will be much faster next time
as it will only need to pull the changes from git since your last run. The script can show the differences from the last run by default but you can
switch that off in your config. Script will show the list of resources for translation (with fuzzy and untranslated strings) on the end.

In working directory script will create/update subdirectories with the following files:
1. Translation catalog xxx.pot file, which can be used for Localize or msgmerge ("msgmerge xxx.pot_lang.po xxx.pot > new_lang.po").
2. Translation file lang.po is there as it's safer for script not to overwrite your translation file if you run it before you pushed that translation.
It's also useful for comparison.
3. Working copy of translation file xxx.pot_lang.po is the one to work on. Downside of additional file is that you have to rename it before commit/push.
4. If there is new_pot_lang.po file present in your current subdirectory you should replace existing file xxx.pot_lang.po with it before translation. If you're not sure how old that file is use msgmerge.



TRANSLATION AND COMMIT
A. It's safer and conveniant to translate file xxx_lang.po in working directory,
B. merge ("msgmerge xxx.pot_lang.po xxx.pot > new_lang.po") and check your translation ("msgfmt -o /dev/null --statistics --check xxx_lang.po"),
C. copy the file xxx_lang.po to git directory with the name lang.po and
D. commit it.


TODO
convert web resources to git
add searching for new *.pot files and other resources and their branches in git
better configurability of messages shown
better documentation

# version of script
# svn info:
# git remote -v

# searching for new resources
# svn list -R:
# git ls-files or git whatchanged

# commit message of script
# svn log -r:
# git log --after=<date>


TIPS SECTION
How to svn co single file (file.pot):
svn checkout $url_of_big_dir $target_dir --depth=empty
svn up $target_dir/$file_you_want