Laravel localization in Portuguese Português

Locale codes

Set the base locale in config/app.php. For regional variants, Portuguese commonly uses: pt_PT, pt_BR, pt_AO, pt_MZ

// config/app.php
'locale' => 'pt',
'fallback_locale' => 'en',

// Or switch at runtime
App::setLocale('pt');

Plural rules: what Portuguese actually needs

CLDR defines 3 cardinal categories for Portuguese. The sample numbers below were computed by ICU for this exact locale:

Laravel's trans_choice() maps numbers to 2 pipe-separated forms for this locale:

// lang/pt/messages.php
'items' => ':count item|:count items'

// Usage
trans_choice('messages.items', $count, ['count' => $count]);

Try any number live in the pluralization tester.

Localized dates with Carbon

Real output for Portuguese (pt locale), generated by Carbon for March 21, 2026:

$date = now()->locale('pt');

$date->translatedFormat('l, j F Y');
// "sábado, 21 março 2026"

$date->isoFormat('LLLL');
// "sábado, 21 de março de 2026 14:30"

$date->isoFormat('L');
// "21/03/2026"

$date->subDays(3)->diffForHumans();
// "há 3 meses"

What to watch out for in Portuguese

• European (pt_PT) and Brazilian (pt_BR) Portuguese differ substantially in vocabulary, spelling, and address (tu vs você); treat them as separate targets.
• Nouns are gendered and adjectives agree in gender and number.
• Decimal comma with dot as thousands separator (1.234,56).

Brazil and Portugal are two locales, not one

Portuguese has around 260 million speakers, the overwhelming majority in Brazil. European and Brazilian Portuguese differ in vocabulary, spelling, grammar and register to a degree that makes a shared translation visibly wrong to at least one audience — considerably more than British and American English differ.

Those are core interface words, not obscure vocabulary. A Portuguese user reading arquivo and usuário knows immediately the product was written for Brazil, and a Brazilian reading ficheiro and utilizador has the same reaction in reverse.

Grammar diverges too. Brazil uses você as the ordinary second-person pronoun with third-person verb forms, while Portugal uses tu informally and você as a mildly formal alternative — so the same pronoun sits at different points on the register scale in the two countries.

Brazil also places object pronouns before the verb where Portugal places them after with a hyphen: me diga against diga-me. This appears constantly in interface copy and is one of the clearest structural tells.

Register differs as well. Brazilian Portuguese is markedly warmer and more direct in commercial writing, while European Portuguese leans formal, so the same source sentence translated faithfully into both produces copy that feels friendly in one market and slightly distant in the other. That is a tone judgement for the translator rather than a rule, and it is one more reason a single shared translation underserves both.

If you can only afford one, Brazilian Portuguese reaches roughly eight times more speakers. But size is not the same as fit — if your market is Portugal, Angola or Mozambique, the European standard is what those users expect.

There is no neutral Portuguese that satisfies both. Attempts to write one produce copy that reads as slightly foreign in both countries rather than natural in either, because the divergence is in everyday words rather than in register or idiom. Pick the market you are actually selling to and commit to it.

Contractions merge prepositions with articles

Portuguese obligatorily contracts prepositions with the articles that follow them. De o is never written; it is do. This is not optional shortening — the uncontracted form is simply ungrammatical.

Since the article depends on the gender and number of the following noun, and the contraction depends on the article, a template that places a preposition before a placeholder cannot produce correct Portuguese. No arquivo, na pasta and nos projetos all correspond to the same English in the.

A template that cannot be corrected

// English: 'Saved in :location'
// Portuguese needs the contraction to agree:
//
//   pasta (fem.)    -> Salvo na pasta
//   arquivo (masc.) -> Salvo no arquivo
//   projetos (pl.)  -> Salvo nos projetos
//
// 'Salvo em :location' is wrong in all three.

Every noun is masculine or feminine, and adjectives and past participles agree with it in gender and number, so status messages built from a shared adjective will be wrong roughly half the time: arquivo salvo but pasta salva.

Portuguese also contracts the demonstratives in the same way — de este becomes deste, em aquele becomes naquele — so the pattern extends well beyond the definite article. Any English source string ending in a preposition before a placeholder is a string that will need restructuring before it can be translated, and it is cheaper to spot that in review than after thirty locales have worked around it.

Diacritics, and the 1990 spelling agreement

Portuguese uses acute, circumflex, grave and tilde accents plus the cedilla, and they are meaning-bearing rather than decorative. Avó is grandmother and avô is grandfather; pode is can and pôde is could.

The tilde on ã and õ marks nasalisation and is not an accent that can be stripped — não without it is not a word. As always, folding diacritics is acceptable for slugs and search normalisation and never for display.

The 1990 Orthographic Agreement standardised spelling across the Portuguese-speaking world and came into force in stages during the 2010s. It removed some silent consonants and changed hyphenation and accent rules, so older and newer spellings of the same word both circulate in real data.

Adopt the post-agreement spelling for new translations, and expect both forms in user-generated data and in older imported content. Search should tolerate the variation rather than treating the two spellings as unrelated words.

Portugal adopted the agreement more reluctantly than Brazil, and European Portuguese still permits some variant forms the Brazilian standard does not, so the two standards did not fully converge. Treat the agreement as having reduced the differences rather than eliminated them, and do not use it as a reason to merge the locales.

Uppercasing requires multi-byte-aware functions, as in every accented language: strtoupper() will corrupt ç, ã and every accented vowel alike. Use mb_strtoupper() or Str::upper(), and note that Portuguese keeps accents on capitals.

Plurals, layout and formatting

Portuguese uses two CLDR plural categories, so trans_choice() takes a two-part string. Formation is mostly regular — add -s after a vowel, -es after most consonants — but words ending in -ão pluralise unpredictably as -ões, -ãos or -ães, so both forms must be written out.

Zero takes the plural, as in English. Portuguese expands roughly twenty to thirty per cent over English, driven by obligatory articles and longer word forms, so buttons and fixed-width labels need room.

Note that the two standards sometimes choose different words of different lengths for the same concept, so a layout verified against Brazilian Portuguese is not automatically safe for the European translation.

Note that Brazil starts the week on Sunday and Portugal on Monday, which affects every calendar component, and that the thousands separator differs between the two. Month names are lowercase in both, and the decimal comma creates the usual numeric-input hazard where floatval() silently discards the fractional part.

Beyond Brazil and Portugal

Portuguese is official in nine countries, and the two European and Brazilian standards do not exhaust the picture. Angola and Mozambique together have tens of millions of speakers and follow the European standard with their own vocabulary; Cape Verde, Guinea-Bissau, São Tomé, East Timor and Macau add smaller populations.

For most products the practical decision remains binary, since African Portuguese-speaking markets are served acceptably by the European standard. But the currency, payment methods and address formats differ entirely, so the locale and the market must be stored as separate facts rather than inferred from one another.

Brazil in particular has payment infrastructure that has no European equivalent. Pix, the instant-payment system, and boleto, a bank-slip method, are both mainstream and expected, and a Brazilian checkout offering only cards will convert poorly regardless of how good the translation is. Identity numbers differ too: Brazil uses CPF for individuals and CNPJ for companies, Portugal uses NIF, and validation written for one rejects the other.

Address forms diverge as well. Brazilian addresses use an eight-digit CEP postcode with its own format, and the street-number convention places the number after the street name. A form laid out for European addresses will fit awkwardly and validate incorrectly.

Set the full locale for formatting rather than a bare pt. The thousands separator, the currency symbol and the first day of the week all differ between Brazil and Portugal, and a bare language code silently applies one country's conventions to the other.

Brazil abolished daylight saving time in 2019 and spans four time zones, so scheduling logic that assumes a single national offset or a southern-hemisphere clock change will drift. Portugal, meanwhile, follows Western European Time with the Azores an hour behind again — two markets, six offsets, and no shared rule between them.

What ships broken most often

• One Portuguese for both markets. Core interface vocabulary differs, and users identify the mismatch immediately.
• Prepositions concatenated to placeholders. Contractions depend on the gender and number of the following noun.
• Adjective agreement in shared strings. Pasta salvo rather than pasta salva.
• Stripped tildes. nao instead of não — not a spelling variant but a non-word.
• Capitalised months. Março instead of março.
• Wrong first day of week. Sunday in Brazil, Monday in Portugal.
• Decimal comma truncating numeric input. The usual silent loss.

Model pt_BR and pt_PT as separate locales from the beginning even if you only translate one. Retrofitting the second after building on a bare pt means auditing every string and reinterpreting every stored user preference, where planning for it costs a locale code in a configuration file.

Install the Laravel-Lang Portuguese files for framework strings, and note that the project maintains Brazilian and European variants separately for exactly the reasons described above. Picking the wrong one gives you several hundred validation messages in the other country's vocabulary, which is precisely the inconsistency that makes a translation feel imported.

Framework strings already translated

Laravel's own validation, auth and pagination strings are maintained in Portuguese by the open-source Laravel-Lang project (MIT). Install them, then manage your app's own strings live:

composer require laravel-lang/common --dev
php artisan lang:add pt
php artisan lang:update