From Mageia wiki
Jump to: navigation, search

Read this first

The website (www.mageia.org) does not depend on a particular framework. It has evolved from scratch from the early first pages. While it may be useful (and perhaps even necessary) to migrate this very www.m.o to a more structured, documented and maintained foundation, one must first understand the whole set of websites, how they relate to each other, how their management differs and how they can be unified somehow through a common top navigation scheme and identity.

It is very slow, ongoing work: improving the existing code, that does not disrupt, but improves on the existing management of the site, codenamed Pinq. It may, or not, be a good path to follow.

You might want to check Website documentation and Atelier Webteam too.

Structure of the website

Code & config

You can check out the code from:

  • git clone mga:web/www

The _nav folder is now a submodule, so after cloning change into the www folder and run:

  • git submodule update --init

Config is done in:

Where should new content go

In en/path-to-your-content. And please regenerate translatable content for the website too.

Organization: (too) many directories

  • root redirection ones: 1, 2, 3, community, about, contribute, donate, downloads, map, migrate, support: they are there only to redirect to the same directory, in the right locale. For instance, HTTP GET http://mageia.org/about/ with Spanish as a preferred language will redirect you to http://mageia.org/es/about/ => can be improved with a redirection rule in the .htaccess
  • locale-based ones: en, fr, es, ru, etc. Contain locale-specific content. Actually, now, the main content is written and localized in the en/ one. All other contain (or must contain) symbolic links to their English equivalent except for really locale-specific content, which translation is better managed by a totally separate document.
  • g: stores all site static assets: stylesheets, javascript, images.
  • langs: stores all localization stuff
  • _nav: local copy of nav.mageia.org code
  • lib: contains various libraries
  • var: technical area
  • tools: various scripts to manage some contents on the site
  • langs.inc.php: defines managed locales, redirections and i18n utilities
  • langs.php: (very misnamed legacy) a kind of a first include to call before all pages
  • app.php, apps, lib/pinq: part of a future change in how the website is served (let's tag this as #Pinq as it is the prefix for the related code)
  • en/downloads, lib/Downloads.php, lib/cached.list.php, lib/mga_geoip.php, lib/maxmind are related to the downloads pages on the site

Code Style Tips

Local Links

Please use relative local links that are i18n friendly. Use of hreflang="en" is not preferable in this case as users expect next web page in the same language anyway.

YES: <a href="../donate/"><?php _g('Donations')?></a>

NO: <a href="/en/donate/"><?php _g('Donations')?></a>

Wiki Links

One suggestion for Wiki links: <?php _g('<a href="https://wiki.mageia.org/en/Mageia_3_Release_Notes" hreflang="en">Release notes</a>')?>

Another possibility: <li><?php _g('<a href="%s">Release notes</a>', array('https://wiki.mageia.org/en/Mageia_3_Release_Notes'))?></li>

Example of translation for both cases in French: <?php _g('<a href="https://wiki.mageia.org/en/Mageia_3_Release_Notes" hreflang="en">Notes de publication</a>')?>

or, when that wiki page is translated: <?php _g('<a href="https://wiki.mageia.org/en/Mageia_3_:_Notes_de_Version_-_FR">Notes de publication</a>')?>

Images

Please use both tags and make them translatable for alt and title in <img> tag like:

<img src="/g/media/covers/3/Mga3_Live_DVD_64_KDE.png" alt="<?php _g('Mageia 3 Live DVD 64 KDE logo')?>" title="<?php _g('Mageia 3 Live DVD 64 KDE logo')?>">

i18n helpers

_r()

Use it when you want to capture a translated string with sprintf() for example. Supersedes deprecated _t() and _d() but does not append space by default.


/**
 * Returns a translated string from global $dictionary
 * it can append space if needed
 *
 * Note that it trims {ok} for translations equal to original too.
 *
 * Use it when you need to capture the string to output.
 *
 * Examples:
 * echo _r("Hello!", ' ') . _r("How are you?")
 * which should return translated: Hello! How are you?
 *
 * @param string $string_for_translation which we want to translate
 * @param string $sufix append (usually space)
 *
 * @return string translated to current locale
*/


_g()

Use it when you want to print a translated string or a string wrapped into a HTML element. Supersedes deprecated _e() and _h() but does not append space by default. It also doesn't add <p> tag by default as _h() does.

/**
 * Higher level function for _r() to echo a translated string from global $dictionary
 * used also to wrap the translation with HTML tags
 * it can also append space if needed
 *
 * Examples:
 *_g("How are you?")
 * will just echo translation
 *
 * _g('Download Mageia %d!', array(5), 'a href="" style="color: blue;"')
 * OR for only one member of array:
 * _g('Download Mageia %s!', 5, 'a href="" style="color: blue;"')
 * will both echo blue link
 *
 * _g("Hey there.", null, ' '); _g("How are you?")
 * will just echo translation: Hey there. How are you?
 *
 * Return boolean.
 * Do not exit the process.
 *
 * @param string $string_for_translation which we want to translate
 * @param array OR string  $args for vsprintf/sprintf
 * @param string $tag_or_space HTML tag or space to append
 *
 * @return null
*/

Website and Internationalisation (i18n)

The translation of Mageia's website is now managed through templates called gettext PO files. A comprehensive guide to the structure of PO files can be found in the official GNU Gettext manual. The following sections will explain how to create/edit content for the website that can be localised, how to generate the gettext PO files using our scripts, and how to adapt the website for a new locale. Convenient report about i18n progress is available here.

How to add a new locale to the website

Say your new locale is named LOCALE and has the code LL.

Required:

  • add LL and LOCALE to $langs in /_nav/lib.php (example for Albanian language).
  • create an LL directory for it at the root of the website; add symbolic links inside it. A quick solution is to copy an existing locale (example for Indonesian ).
  • create a directory structure langs/LL (example for Indonesian ) or copy it from transifex in CLI: tx pull -l LL. Note that you need to cd into ./langs first.

How to create/edit translatable content for the website

Example of a procedure (CLI commands are executed from your local already cloned git root of www.mageia.org):

  • Refresh from git.
git pull
  • Modify all pages you need for that change. Use suitable string helpers in each particular case.
  • Run rebuild_gettext_catalogs.sh script (msgmerge & polib tools are needed, it's rpms: gettext python-polib) to recreate all gettext catalogs. Repair errors reported from the script if any. Note that you need to restore target pot file(s) before you can rebuild it/them.
urpmi gettext python-polib # install them as root if needed (only once)
./tools/rebuild_gettext_catalogs.sh # if you need to rebuild the target file first run git checkout langs/en/target.pot
  • Check the success of the script locally in the non English language if you know any.
  • Commit and push to git.
git commit -m "page mga 5"
git push
  • Please check the success of target page(s) on www.mageia.org too! Note that commit doesn't come live instantly but within 5 minutes.
  • It's nice to translators if you push changed pot files directly to Transifex (cauldron in this example)
tx push --source --resource=mageia.page-cauldron
tx push --translations --language=your_language_code --resource=mageia.page-cauldron # if you want to push your language also

Manage download web page for new release (cauldron)

  • update 'en/downloads/get/definitions.ini' which contains info about file that can be downloaded via mirror
  • to complete this you could use fidd. It will create a text.ini that can be copied & pasted to the previous one
  • update netinstall for cauldron iso name (optionally md5 - sha1sum and others too {)
  • update 'en/$version/download_index.php'
  • $release set the release (alpha1/beta2/rc)
  • $torrentavailable is a boolean, if torrents are available set it to true, if not to false
  • $classical is a boolean, if classical install are available set it to true, if not to false
  • $live is a boolean, if LiveCD/DVDs are available set it to true, if not to false
  • $dual is a boolean, if DualArch iso is available set it to true, if not to false
  • update cached mirror list if needed 'lib/cached.list.php'
  • in the file 'lib/Downloads.php line 180 "$test_file = $item['url'].'/iso/5/torrents/Mageia-5-LiveDVD-KDE4-x86_64-DVD.torrent';" updates the file to have last inside repo:
  • run php tools/update-mirrors-list.php
  • it will update all cached.lists especially cached.list.php which has all mirrors (taken from api from mirror.mageia.org) that have the specified file, and removing others without it
  • update also other web pages connected with the release of a new version:

doc.mageia.org

Procedure of adding pdf and epub files for download

  • ftp part
  • Prepare local directory structure like existing one.
  • Copy the files inside with the proper names (./doc/mgaXX/pdf|epub/installer|mcc|draklive/MageiaXX-DrakX|MCC-lang.pdf|epub). Directory structure and filenames must be like that so that DL works.
  • Add date.txt file (suggestion: echo Mageia XX > date.txt && LC_ALL=C date >> date.txt) in the ./doc/mgaXX/ so the mirrors can be checked later.
  • Now upload all of them to the marcom ftp space.
  • Allow the mirrors at least a few hours to propagate the files.
  • www.mageia.org part

Procedure of adding html documentation files and pictures

  1. download an archive from docteam.mageia.org.uk/zipped/<manual>/<language>/ (you can use script autodownload.py for that or a wget command; for aexample: wget --directory-prefix=./draklive/ --timestamping --no-host-directories --recursive --no-directories --no-parent --accept zip http://docteam.mageia.org.uk/zipped/draklive/)
  2. store it anywhere else than your git clone of the documentation repository
  3. make sure your git clone is up to date and has no uncommitted changes
  4. in a terminal go into your git clone root and run:
    python3 update_manual.py <manual_name> <release> <language> <archive_path_and_name>
    this script should:
    • check for differences between your git clone for this manual in this release and language,
    • unzip the archive in your git clone,
    • move the common folder if it's an English manual, remove it if not,
    • fix the links to the common folder in the html files,
    • fix the links of missing images (add link to EN ones)
    • and execute the "git add" and "git rm" commands.
  5. check locally that the manual seems fine
  6. run git commit to store this new version
  7. go back to step 1 for the next archive
  8. git push at the end

For each manual/release, English should be done first.

Git memento

Navigation bar

Inside git, the repository of nav bar is a bit particular. Previously on the svn, there were two of them. One in web/www/_nav and the other in web/nav. Since the conversion to git, _nav is now a sub-module, so the previous way to do this has changed.

When you check out a fresh clone you will need to initialize the nav submodule from inside the www (git root) folder:

git submodule update --init 

If content changes in the master repository nav folder, you will need to update your clone to reflect the changes:

git submodule update

Once that is done, change into the _nav folder and pull in any changes there (assuming you're already in the clone's www folder):

cd _nav
git checkout master
git pull

Now you can edit any files in _nav.

After making changes, commit and push your changes to the nav submodule, then go back to the www folder:

git commit
git push
cd ..

Finish committing and push from inside the www (git root) folder:

git add _nav
git commit -m "Update _nav submodule to latest git" _nav
git show
git push
"This feels wrong as you're adding a folder, but really you're telling www git repo to add a reference to the current master commit of the nav git repo." -- comment from Colin

If you only need to sync your clone with the latest nav submodule:

git submodule update && cd _nav && git checkout master && git pull && cd ..

Updating working mirrors caching lists

Options for deleting feed and navigation cache

Option for deleting feed cache if blog posts are not parsed properly:

https://www.mageia.org/test/lang.php?delete_feed_cache=1

Option for deleting navigation cache if pages in one language are blank or not parsed properly:

https://www.mageia.org/test/lang.php?delete_nav_cache=1

Testing tools

TODO

Improve and document tools:

fidd
php lib/t/00_downloads.t
php lib/t/01_mga_geoip.t
php lib/t/02_downloads_definitions.t
php lib/t/03_lang_redirection.t