Debian webpagina's vertalen

Om de taak van vertalers zo makkelijk mogelijk te maken, worden de pagina's iets anders gegenereerd dan velen onder u gewend zijn. De webpagina's worden namelijk gegenereerd van broncode in wml-opmaak. Voor elke taal is er een aparte map.

Indien u van plan bent met een volledig nieuwe vertaling van de Debian website te beginnen, lees dan de paragraaf over het beginnen van een nieuwe vertaling.

Afzonderlijke pagina's vertalen

We gebruiken WML om de specifieke inhoud van een pagina te scheiden van de elementen die gemeenschappelijk zijn voor meerdere pagina's. Dit houdt in dat men bepaalde WML-broncodebestanden moet bewerken in plaats van HTML-bestanden. Gebruik Git om de huidige broncode te verkrijgen. U moet ten minste twee mappen ophalen: webwml/english/ en webwml/<taalcode>/.

Om een afzonderlijke pagina uit het Engels naar uw taal te vertalen, moet het originele wml-bestand vertaald worden en in de map van de andere taal geplaatst worden. Het relatieve pad en de naam moeten hetzelfde zijn als van de Engelse map, zodat de links blijven werken.

Kopteksten van de vertaling

Het wordt sterk aanbevolen om als vertaler een extra regel toe te voegen aan de kopteksten na de laatste #use-opdracht, om de exacte commit-hash van het originele bestand dat vertaald werd, vast te leggen, waardoor een latere opwaardering ervan makkelijker wordt. De regel ziet er zo uit:: #use wml::debian::translation-check translation="<git_commit_hash>" Merk op dat, indien u het te vertalen bestand genereert met het hulpmiddel copypage.pl (hetgeen we sterk aanraden), de git commit-hash automatisch gegenereerd wordt. Het gebruik van copypage.pl wordt in de navolgende tekst uitgelegd.

Sommige vertaalteams gebruiken deze regel ook om aan te geven wie de officiële vertaler is van elke webpagina. Wanneer u dit doet, zult u een automatisch e-mailbericht ontvangen wanneer een pagina die u onderhoudt, in het Engels bijgewerkt werd, zodat u voor een aangepaste vertaling kunt zorgen. Daarvoor voegt u gewoon uw naam als onderhouder toe aan de #use-regel, zodat deze er als volgt uitziet: #use wml::debian::translation-check translation="git_commit_hash" maintainer="uw naam". Het gereedschap copypage.pl zal dit automatisch doen, als u de omgevingsvariabele DWWW_MAINT instelt of als u aan de commandoregel de schakeloptie -m gebruikt.

De kopregels van de webpagina kunnen eenvoudig gegenereerd worden door het script copypage.pl in de webwml hoofdmap te gebruiken. Het script kopieert de pagina naar de juiste plaats, maakt zo nodig mappen en make-bestanden aan en voegt automatisch de nodige kopregels toe. U zult een waarschuwing krijgen mocht een te kopiëren pagina reeds bestaan in het archief, zij het omdat de pagina uit het archief verwijderd werd (omdat deze te verouderd was), of omdat iemand reeds een vertaling in het archief plaatste en uw kopie ervan niet meer actueel is.

Om te beginnen met het gebruik van het gereedschap copypage.pl, configureert u het bestand language.conf in de webwml hoofdmap. Dit bestand zal gebruikt worden om te bepalen naar welke taal u vertaalt. Dit bestand moet maximaal uit twee regels bestaan. Op de eerste regel staat de naam van de taal (zoals dutch) en de facultatieve tweede regel kan de naam bevatten van de persoon die de vertaling onderhoudt. U kunt de taal ook instellen met de omgevingsvariabele DWWW_LANG, en de omgevingsvariabele DWWW_MAINT kunt u gebruiken om er uw naam in te plaatsen, zodat deze toegevoegd wordt aan de kopregel van de gegenereerde wml-bestanden als onderhouder van de vertaling. Een derde mogelijkheid is om de taal en (facultatief) de onderhouder van de vertaling op te geven aan de commandoregel via bijvoorbeeld -l dutch -m "Donald Duck" en het bestand language.conf helemaal niet te gebruiken. Het script biedt nog andere functionaliteit. Voer het commando uit zonder argumenten om informatie daarover te verkrijgen.

Nadat u bijvoorbeeld het commando ./copypage.pl bestand.wml gegeven heeft, kunt u in het bestand de originele tekst vertalen. Commentaar in het bestand zal aangeven of er elementen zijn die niet vertaald zouden mogen worden. Respecteer dit. Wijzig niet onnodig de opmaak. Indien er iets gerepareerd moet worden, zal dit waarschijnlijk in het originele bestand moeten gebeuren.

Pagina compileren en publiceren

Aangezien we gebruik maken van onderhandelen over de inhoud (content negotiation), krijgen HTML-bestanden niet de naam bestand.html, maar wel bestand.<taal>.html, waarbij <taal> de tweelettercode voor de taal is, overeenkomstig ISO 639 (bijv. nl voor Nederlands).

U kunt het HTML-bestand bouwen vanuit het WML-bestand met de opdracht make bestand.<taal>.html. Als dat lukt, controleert u of de syntaxis volledig correct is met het commando weblint bestand.<taal>.html.

OPMERKING: regelmatig worden de webpagina's automatisch vanuit de wml broncode in git opnieuw gecompileerd op de server www-master. Voor het grootste gedeelte is dit proces immuun voor fouten. Indien u echter een defect bestand laat opnemen in het basisniveau van uw vertaling (bijvoorbeeld het basisbestand index.wml), zal dit het compilatieproces ontregelen en alle andere updates aan de website tegenhouden. Besteed dus bijzondere aandacht aan deze bestanden.

Zodra de pagina klaar voor gebruik is, kunt u ze toepassen in het git-archief. Indien u er zelf toe gerechtigd bent, moet u de commits pushen naar het webwml git-archief; indien niet, stuur deze dan naar iemand met schrijftoegang tot het archief.

Een nieuwe vertaling beginnen

Indien u wilt beginnen met het vertalen van de webpagina's van Debian naar een nieuwe taal, stuur ons dan een e-mail (in het Engels) naar het adres webmaster@debian.org.

Eerst en vooral kloont u onze broncodeboom, zoals beschreven wordt op onze introductiepagina over Git.

Nadat u een git checkout uitgevoerd heeft, maakt u een basismap aan voor uw vertaling, op hetzelfde niveau als english/ en de andere talen. De naam van de map voor de vertaling moet in het Engels zijn en mag enkel bestaan uit kleine letters (bijv. "dutch" en niet "Nederlands").

Kopieer de bestanden Make.lang en .wmlrc vanuit de map english/ naar de map voor de nieuwe taal. Deze bestanden zijn essentieel om uw vertalingen te kunnen compileren vanuit de WML-bestanden. Zij zijn zo opgevat dat u enkel nog de volgende dingen moet aanpassen, nadat u ze naar de map voor de nieuwe taal gekopieerd heeft:

  1. In het bestand Make.lang moet de variabele LANGUAGE aangepast worden.
  2. In het bestand .wmlrc moeten de variabelen CUR_LANG, CUR_ISO_LANG en CHARSET aangepast worden. Voeg de variabele CUR_LOCALE toe indien u deze nodig heeft voor het sorteren.
  3. Sommige talen hebben mogelijk extra verwerking nodig om met de tekenset om te gaan. Dit kan gedaan worden met de wml-opties --prolog en --epilog. Gebruik hiervoor de variabelen WMLPROLOG en WMLEPILOG in Make.lang.
  4. In het bestand webwml/Makefile uit de basismap moet de variabele LANGUAGES aangepast worden, opdat uw taal op www.debian.org samen met de andere talen gecompileerd zou worden. We geven er de voorkeur aan dat u deze specifieke aanpassing overlaat aan de webmasters. U zou het namelijk niet weten mocht uw vertaling defect blijken te zijn bij het opnieuw laden ervan uit het VCS-systeem. Maar dit zou het bouwproces van de rest van onze website wel defect maken.

Als dat gedaan is, neemt u de volgende regel op in een nieuw bestand genaamd "Makefile" in die map: 

include $(subst webwml/de_map_voor_uw_taal,webwml/english,$(CURDIR))/Makefile

(Vervang de_map_voor_uw_taal door de naam van de map die uw taal bevat.)

Maak nu binnen de map voor uw taal een onderliggende map met de naam "po" en kopieer hetzelfde Makefile-bestand naar die onderliggende map (cp ../Makefile .).

In de map po/ voert u het commando make init-po uit om de initiële set *.po-bestanden aan te maken.

Nu u het raamwerk opgezet heeft, kunt u beginnen uw vertalingen in te voegen in de gedeelde WML-tags welke in sjablonen gebruikt worden. De eerste sjablonen welke u zou moeten vertalen, zijn deze die op alle webpagina's voorkomen, zoals de trefwoorden uit de koptekst, de elementen uit de navigatiebalk, en de voettekst.

Begin met de vertaling van het bestand po/templates.xy.po, (waarbij xy de tweelettercode is voor uw taal). Voor elke msgid "iets" is er initieel een msgstr "" waar u de vertaling van iets tussen de dubbele aanhalingstekens na msgstr kunt invullen.

Het is niet nodig alle tekenreeksen in alle .po-bestanden te vertalen, enkel deze welke u voor de momenteel vertaalde pagina's nodig heeft. Om te weten te komen of het nodig is om een tekenreeks te vertalen, kijkt u naar het commentaar in het .po-bestand net boven elke msgid-frase. Indien het bestand waarnaar verwezen wordt, zich bevindt in english/template/debian, dan zult u deze hoogstwaarschijnlijk moeten vertalen. Zo niet, dan kunt u de vertaling ervan tot een later moment uitstellen, wanneer u daadwerkelijk de betreffende sectie van de webpagina's die dit bestand nodig hebben, vertaalt.

Het doel van .po-bestanden is om de zaken makkelijker te maken voor vertalers, zodat ze (bijna) nooit iets moeten bewerken in de map english/template/debian zelf. Indien u iets vindt dat op een foutieve wijze opgezet werd in de map templates, zorg er dan voor dat dit probleem op een algemene manier aangepakt wordt (vraag gerust iemand anders om dit voor u te doen), in plaats van vertalingen in de sjablonen vast te leggen, wat (gewoonlijk) een groter probleem zou opleveren.

Indien u twijfelt of u iets op de juiste manier gedaan heeft, vraag dit dan op de debian-www mailinglijst voordat u iets vastlegt in het git-archief.

Opmerking: indien u het nodig vindt nog meer aanpassingen te maken, stuur dan een e-mail naar debian-www waarin u uitlegt wat u veranderde en waarom, zodat het probleem gecorrigeerd kan worden.

Nadat u klaar bent met het sjabloonraamwerk, kunt u beginnen met het vertalen van de startpagina en de andere *.wml-bestanden. Om een lijst te zien van eerst te vertalen pagina's, raadpleegt u de pagina met suggesties. Vertaal *.wml-pagina's zoals beschreven bovenaan deze pagina.

Verouderde vertalingen nieuw leven inblazen

Zoals beschreven wordt in hoe vertalingen actueel houden, kunnen verouderde vertalingen van de website automatisch verwijderd worden na een lange periode zonder enige actualisering.

Indien u vindt dat bepaalde bestanden ooit in het verleden verwijderd werden, welke u nu terug zou willen opvragen om deze verder te bewerken, kunt u zoeken in de commit-geschiedenis met behulp van de standaardcommando's van git.

Bijvoorbeeld, als het verwijderde bestand "verwijderd.wml" heette, kunt u de geschiedenis doorzoeken met het commando:

   git log --all --full-history -- <pad/naar/bestand/verwijderd.wml>

U kunt de exacte vastlegging (commit) te weten komen waarmee het bestand verwijderd werd, samen met de hash van die vastlegging. Om gedetailleerde informatie te zien over welke wijzigingen er in deze vastlegging aan het bestand aangebracht werden, kunt u het subcommando git show gebruiken:

  git show <COMMIT_HASH_STRING> -- <pad/naar/bestand/verwijderd.wml>

Indien de vastlegging exact deze is waarmee het bestand verwijderd werd, kunt u het bestand naar de werkruimte terughalen met het commando git checkout:

  git checkout <COMMIT_HASH_STRING>^ -- <pad/naar/bestand/verwijderd.wml>

Nadat u dit gedaan heeft, moet u het document uiteraard eerst bijwerken voordat u het opnieuw incheckt, anders zou het opnieuw verwijderd kunnen worden.

De rest van het verhaal

Met de bovenstaande beschrijving weet u waarschijnlijk voldoende om aan de slag te gaan. Later zult u wellicht de volgende documenten willen naslaan waarin u meer gedetailleerde uitleg en bijkomende nuttige informatie kunt vinden.

We hopen dat u zult vinden dat het werk dat we geleverd hebben, u het vertalen van de pagina's zo makkelijk mogelijk maakt. Zoals eerder aangegeven, kunt u met eventuele vragen terecht op de mailinglijst debian-www.