11: Vertalingen

Phlo gebruikt de lang resource voor meertalige view-tekst en vertaling. In views schrijf je statische tekst bij voorkeur met de compacte taalafkorting. Je schrijft brontekst in je eigen taal; de onderstaande voorbeelden gebruiken Nederlands (nl) als brontaal.

11.1: View afkorting

De standaardvorm voor statische vertaalbare tekst in een view is:

view:
<p>{nl: Hallo wereld}</p>

De taalcodes voor de dubbele punt is de brontaal van de tekst. Als %app->lang dezelfde taal is, wordt de tekst zoals deze is weergegeven. Als de actieve taal verschilt, gebruikt %lang de vertaalcache en plant het ontbrekende vertalingen asynchroon in.

De afkorting is alleen voor statische tekst. Alles tussen de dubbele punt en de sluitende accolade wordt een enkele stringargument: {nl: Hallo wereld} compileert naar {{ nl('Hallo wereld') }}, dus er is geen placeholder of argumentsyntaxis binnenin.

Voor dynamische waarden, roep je de nl() / en() functie aan in een expressie. Deze nemen sprintf-stijl argumenten:

view($name):
<p>{{ nl('Hallo %s', $name) }}</p>

De %s bevindt zich in de vertaalde brontaalstring (zodat de cache-sleutel stabiel blijft), en het argument wordt na vertaling vervangen. Gebruik de afkorting voor statische tekst en de functie wanneer je moet interpoleren.

11.2: Helpers in code

De huidige lang resource biedt globale hulpfuncties voor het Nederlands en het Engels:

method title => nl('Welkom')
method intro => en('Build compact full-stack apps')

Deze hulpfuncties zijn nuttig in methods, props of controller code. In views blijft de afkorting meestal duidelijker:

view:
<h1>{nl: Welkom}</h1>
<p>{en: Build compact full-stack apps}</p>

11.3: Actieve taal

De actieve taal staat op %app->lang. Een route kan deze instellen voordat de view wordt gerenderd:

route both GET $lang:nl,en=nl guide {
    %app->lang = $lang
    view($this)
}

In links kun je %lang gebruiken als een objectwaarde om de huidige taal weer te geven of te verwerken.

11.4: Vertaalcache

Vertalingen worden per taal geladen vanuit langs/ via %INI(%app->lang, langs). Ontbrekende vermeldingen worden asynchroon vertaald op basis van hun hash en later uit de cache gelezen.

De kernmethoden zijn:

%lang->translation('nl', 'Hallo wereld')
%lang->translate('nl', 'en', 'Hallo wereld')

Gebruik translation() voor normale app-rendering met caching en asynchrone aanvulling. Gebruik translate() alleen wanneer je opzettelijk een enkele directe vertaling wilt uitvoeren.

11.5: Vertaalinstructies

De lang resource voedt een AI-vertaler, en je kunt deze sturen. De instructions property is extra context die de vertaler bij elke vertaling ontvangt: jouw domein, jouw terminologie en regels over wat letterlijk moet blijven. Een app injecteert het met een build mod:

prop %lang.instructions = 'Documentatie voor de Phlo-taal. Houd sleutelwoorden zoals route, view en prop in het Engels. Houd algemene Engelse technische termen (best practices, deployment, release) onvertaald waar dat natuurlijk leest, en geef de voorkeur aan natuurlijke formuleringen boven geforceerde, letterlijke vertalingen.'

Zonder instructies werkt de vertaler alleen vanuit de tekst. Gebruik ze om eigennamen en sleutelwoorden intact te houden en om geforceerde vertalingen van termen die al gebruikelijk zijn in de doeltaal te vermijden. De standaard is void. Dezelfde instructies bereiken ook markdown-documentatie die is vertaald via de docs machinery, die %lang->instructions leest.

11.6: Best practices

• Gebruik {nl: ...} en {en: ...} in views voor statische tekst; gebruik nl() / en() voor alles met argumenten.
• Gebruik nl() en en() in PHP/Phlo code buiten views.
• Stel %app->lang vroeg in, in de route of een centrale controller in.
• Houd de brontekst stabiel; gewijzigde tekst krijgt een nieuwe hash.
• Stel %lang.instructions in zodat de vertaler je terminologie behoudt en gedwongen vertalingen vermijdt.
• Documenteer alleen taalhelpers die daadwerkelijk bestaan als resource functies.