# Translation guidelines: context & copywriting

**Standard:** All copy (EN and translations) follows a **senior SEO copywriting** standard: clear, benefit-led, confident, no fluff. Think Criazo-level clarity. The English source (`en/messages.php`) has been refined to this standard, use it as the intent reference.

Translations should **not** be literal (word-for-word). They must read as **native, persuasive copy** in each language, with **context** and **SEO** in mind.

---

## Core principle

- **English** = source of meaning and intent, not the literal text to transpose.
- **Target language** = how a local copywriter would say it for that audience (tone, idioms, search behaviour, trust).

Use this doc when editing `resources/lang/{locale}/messages.php` or when briefing translators.

---

## By section: intent & context

### Meta & SEO (`meta.*`, page `meta_title`, `meta_description`, `meta_keywords`)

- **Intent:** Search visibility + click-through. Users see this in Google.
- **Tone:** Clear, benefit-led, professional. Include terms people actually search for in that language/locale.
- **Do:** Use local SEO phrasing (e.g. PT: "agência de marketing digital Lisboa" if relevant; BR: "marketing digital para empresas").
- **Avoid:** Translating the English sentence structure; generic keywords that nobody searches.

### Hero (`hero.*`)

- **Intent:** First impression, value proposition, trust. Above the fold.
- **Tone:** Confident, benefit-led, action-oriented. Not corporate jargon.
- **Do:** Short, punchy headlines; CTAs that sound like natural calls to action in that language.
- **Avoid:** Literal translations of "Delivers Results", "Get Free Consultation"; long, passive sentences.

### CTAs (buttons, links)

- **Intent:** Drive clicks and conversions.
- **Tone:** Direct, second person ("you"), active verb. Same energy as good ad copy.
- **Do:** "Fale connosco" / "Fale conosco", "Pedir orçamento", "Ver casos de sucesso": how a local user would say it.
- **Avoid:** "Obtenha uma consulta gratuita" if in your locale people say "Consulta grátis" or "Fale com um especialista".

### Services / benefits lists

- **Intent:** Scannable, benefit-focused. Build trust and clarity.
- **Tone:** Consistent, concrete (numbers, outcomes where possible).
- **Do:** Keep bullet points parallel in structure; use terms the industry uses in that market (e.g. "tráfego orgânico", "conversões").

### Navigation & UI

- **Intent:** Clarity and accessibility.
- **Tone:** Short, standard where conventions exist (e.g. "Contacto" pt-PT vs "Contato" pt-BR).
- **Do:** Match platform/UX norms for that locale.

---

## Locale-specific notes

### Portuguese (Portugal): `pt`

- **Formal you:** "o seu", "a sua", "si" where appropriate for B2B.
- **SEO:** Include "Portugal", "Lisboa" where relevant; "agência marketing digital Portugal".
- **CTAs:** "Saber mais", "Ver mais", "Pedir orçamento", "Fale connosco" feel natural.
- **Avoid:** Brazilian-only terms if the site targets PT users (e.g. "estoque" → "inventário" in pt-PT).

### Portuguese (Brazil): `br`

- **Tone:** Slightly more direct and colloquial; "seu/sua" is standard.
- **SEO:** "marketing digital Brasil", "agência digital São Paulo" (or relevant city).
- **CTAs:** "Consultoria gratuita", "Fale conosco", "Saiba mais", "Solicitar orçamento".
- **Terminology:** "estoque", "site", "contato", "celular" (not "inventário", "website", "contacto", "telemóvel").

### Other locales (ES, FR, DE, IT, etc.)

- Apply the same idea: **context over literal translation**. Prefer how a native copywriter would write for that market and for SEO in that language.

---

## Examples: literal vs copywriting-style

### Hero main title

| Approach   | Example (EN → PT) |
|-----------|--------------------|
| Literal   | "Transforme o seu negócio com marketing digital que entrega resultados" (ok but generic) |
| Copywriting | "Marketing Digital que Aumenta Vendas e Visibilidade" or "O Seu Negócio a Crescer Online: Com Resultados Medíveis" (benefit-led, more concrete) |

### Meta description

| Approach   | Example (EN → PT) |
|-----------|--------------------|
| Literal   | "Transforme o seu negócio com serviços especializados de marketing digital. 9+ anos..." (correct but flat) |
| Copywriting | "Agência de marketing digital em Portugal. Sites, SEO, redes sociais e Google Ads. +189 projetos. Orçamento sem compromisso." (local, concrete, CTA) |

### CTA button

| Approach   | Example |
|-----------|---------|
| Literal   | "Obtenha uma consulta gratuita" (long, formal) |
| Copywriting | "Consulta Grátis" / "Fale com um Especialista" (short, action-oriented) |

---

## Workflow tips

1. **When adding new EN strings:** Add a short comment in the EN file for high-impact strings (hero, meta, main CTAs) explaining intent, e.g. `// CTA: action-oriented, low friction`.
2. **When translating:** Read the whole section (e.g. hero) in EN, then write the same section in the target language as if you were writing original copy.
3. **SEO:** Check what phrases rank in that country (Google Trends, keyword tools in that language) and weave them naturally into meta and headings.
4. **Review:** Ask a native speaker to read the page in that language; if it "sounds translated", rephrase for natural flow and tone.

---

## Required keys for every locale

Every locale file (including new ones: fr, de, it, nl, pl, br, da, sv, etc.) **must** include these keys so system and error pages are native in that language:

- **`errors.404_title`**: Page not found (or equivalent). Used as meta title and heading on 404 page.
- **`errors.404_message`**: Short message shown on 404 (e.g. "This page doesn't exist or has been moved."). Native, helpful tone.

Without these, the 404 page falls back to English. Add an `'errors' => ['404_title' => '...', '404_message' => '...']` block in each locale's override (or in the full file when creating a new locale).

---

## File reference

- Source of truth (intent): `resources/lang/en/messages.php`
- Locales: `pt`, `br`, `es`, `fr`, `de`, `it`, `nl`, `pl`, `da`, `sv`
- All user-facing strings live under `messages.*` and are used via `__('messages.hero.main_title')` etc.