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 zijn de brontalen 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.

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

Voor dynamische waarden, roep 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 brontekst (zodat de cache-sleutel stabiel blijft), en het argument wordt na de 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 helpers zijn nuttig in methoden, props of controllercode. 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 bevindt zich 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 async backfill. 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 = 'Documentation for the Phlo language. Keep keywords like route, view and prop in English. Keep common English technical terms (best practices, deployment, release) untranslated where that reads naturally, and prefer natural phrasing over forced, over-literal translation.'

Zonder instructies werkt de vertaler alleen vanuit de tekst. Gebruik ze om de juiste namen en trefwoorden intact te houden en om stijve vertalingen van termen die al gebruikelijk zijn in de doeltaal te vermijden. De standaard is void. Dezelfde instructies gelden ook voor markdown-documentatie die is vertaald via de docs-machine, 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.