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 zinnens bent met een volledig nieuwe vertaling van de Debian website te beginnen, moet u de paragraaf over een nieuwe vertaling beginnen raadplegen.

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 op te halen. U moet minstens twee mappen ophalen via het commando git checkout: 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 moet u gewoon uw naam als onderhouder toevoegen aan de #use-regel, zodat deze er zo 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 fel 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, moet u het bestand language.conf in de webwml hoofdmap configureren. Dit bestand zal gebruikt worden om uit te maken 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 lukte moet u nagaan 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 de webpagina's van Debian naar een nieuwe taal wilt beginnen vertalen, moet u ons een e-mail (in het Engels) sturen naar het adres webmaster@debian.org.

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

Nadat u een git checkout uitgevoerd heeft, moet u een basismap aanmaken 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 u hiermee klaar bent, moet u de volgende regel opnemen in een nieuw bestand in die map met als naam "Makefile":

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

(Vervang uiteraard 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/ moet u het commando make init-po uitvoeren om de initiële set *.po-bestanden aan te maken.

Nu u het raamwerk opgezet heeft, kunt u uw vertaling beginnen invoegen 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 tussen de dubbele aanhalingstekens na msgstr de vertaling van iets moet invullen.

U dient niet alle tekenreeksen in alle .po-bestanden te vertalen, enkel deze welke voor de momenteel effectief vertaalde pagina's nodig zijn. Om te weten of u een tekenreeks moet vertalen, moet u in het .po-bestand naar de commentaar kijken welke juist boven elke msgid-frase staat. Indien het bestand waarnaar verwezen wordt, zich bevindt in english/template/debian, dan zult u deze hoogstwaarschijnlijk moeten vertalen. Is dit niet het geval, dan kunt u de vertaling ervan naar later uitstellen, tot het moment waarop u de betreffende sectie van de webpagina's waarvoor ze nodig is, effectief vertaalt.

Het doel van .po-bestanden is om de zaken makkelijker te maken voor vertalers, zodat ze zelf (bijna) nooit iets moeten bewerken in de map english/template/debian. 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 het in uw plaats te doen), eerder dan effectieve vertalingen in de sjablonen vast te leggen, wat (gewoonlijk) een groter probleem zou geven.

Indien u twijfelt of u iets op de juiste manier gedaan heeft, stel daar dan een vraag over op de mailinglijst debian-www voor u iets vastlegt in het git-archief.

Opmerking: indien u vindt dat u eventueel nog andere aanpassingen moest 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 de vertaling van de startpagina en de andere *.wml-bestanden. Om een lijst te zien van eerst te vertalen pagina's, kunt u de pagina met suggesties raadplegen. Vertaal *.wml-pagina's welke bovenaan deze pagina vermeld worden.

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 vooraleer u het opnieuw incheckt, anders zou het opnieuw verwijderd kunnen worden.

De rest van het verhaal

Met de bovenstaande beschrijving weet u wellicht voldoende om aan de slag te gaan. Later zult u wellicht de volgende documenten erop 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 we al aangegeven hebben, kunt u met eventuele vragen terecht op de mailinglijst debian-www.