Translation File Examples

Purpose and Scope

This document demonstrates the structure and format of translation files through concrete examples. The primary focus is the bundled lang/en/validation.php file, which exemplifies nested message structures, custom rule overrides, and attribute mappings. This page shows actual translation file content and explains how different file formats organize translation data.

For details on how FileLoader loads these files from disk, see page 5.1. For information on in-memory translation storage, see page 5.2.

---

Translation File Types

The package supports two file formats:

Format	Extension	Loaded By	Access Pattern
PHP Arrays	.php	$this->files->getRequire($full) at src/FileLoader.php97-98	group.key or namespace::group.key
JSON Objects	.json	json_decode($this->files->get($full)) at src/FileLoader.php114-115	Direct string keys

PHP files support nested arrays and comments. JSON files provide flat key-value mappings.

Sources: src/FileLoader.php46-57 src/FileLoader.php93-103 src/FileLoader.php110-126

---

Directory Structure Example

lang/
├── en/
│ ├── validation.php # Validation messages (lines 1-200)
│ ├── messages.php # General messages
│ └── auth.php # Authentication messages
├── es/
│ ├── validation.php
│ └── messages.php
├── en.json # Flat JSON translations
├── es.json
└── vendor/
 └── packagename/
 └── en/
 └── messages.php # Override package translations

Path Resolution by FileLoader:

The FileLoader constructs file paths based on the translation key format:

• validation.required → {path}/en/validation.php → $array['required']
• Welcome → {path}/en.json → $json['Welcome']
• pkg::messages.title → {hints['pkg']}/en/messages.php → $array['title']

Sources: src/FileLoader.php46-57 src/FileLoader.php93-103 src/FileLoader.php110-126

---

PHP File Format

Basic Array Structure

PHP translation files return associative arrays. Example minimal file:

Saved as lang/en/messages.php, access with trans('messages.welcome') or __('messages.welcome').

Sources: lang/en/validation.php1-5

Placeholders with Colon Prefix

Placeholders use :name syntax for runtime replacement:

The Translator replaces placeholders via makeReplacements() in src/Translator.php220-246

Sources: lang/en/validation.php20 lang/en/validation.php42 lang/en/validation.php121

Nested Arrays for Type-Based Messages

Some rules need different messages based on data type. From lang/en/validation.php29-34:

Access via trans('validation.between.numeric'). The validator selects the appropriate sub-key based on field type.

Sources: lang/en/validation.php29-34 lang/en/validation.php92-97 lang/en/validation.php101-106

---

Validation File as Comprehensive Example

The lang/en/validation.php file demonstrates all translation file features in a real-world context.

File Structure Overview

Sources: lang/en/validation.php1-200

Section 1: Simple Validation Messages

Lines 17-147 contain single-level validation rules. Examples:

Each message includes the :attribute placeholder, replaced at runtime with the field name.

Sources: lang/en/validation.php17 lang/en/validation.php53 lang/en/validation.php120 lang/en/validation.php142

Section 2: Type-Based Nested Messages

Lines 29-165 contain rules with different messages per data type:

Key Access Pattern:

• trans('validation.between.numeric') → "The :attribute must be between :min and :max."
• trans('validation.max.file') → "The :attribute may not be greater than :max kilobytes."

Sources: lang/en/validation.php29-34 lang/en/validation.php92-97 lang/en/validation.php148-153

Section 3: Custom Message Overrides

Lines 177-181 define the custom array structure for per-field rule overrides:

Usage Example:

Access via trans('validation.custom.email.required'). Validators check custom messages before falling back to default rules.

Sources: lang/en/validation.php177-181

Section 4: Attribute Name Mappings

Line 194 contains the attributes array for mapping field names to human-readable labels:

Populated Example:

When validation fails on field email, :attribute placeholder is replaced with "email address" instead of "email".

Sources: lang/en/validation.php194

Section 5: Conditional Validation Messages

Lines 148-165 show conditional rules that reference other fields:

These messages include :other and :value placeholders to reference related fields and their values.

Sources: lang/en/validation.php18 lang/en/validation.php121 lang/en/validation.php160-165

Complete Translation Key Mapping

Sources: lang/en/validation.php1-200

---

JSON File Format

Flat Key-Value Structure

JSON files provide simple flat translations without group prefixes:

Saved as lang/en.json, access with __('Welcome') or trans('Good morning').

Loading via loadJsonPaths()

The FileLoader detects JSON requests when group === '*' at src/FileLoader.php48-49:

The loadJsonPaths() method at src/FileLoader.php110-126 merges all matching JSON files:

Comparison: PHP vs JSON

Feature	PHP Arrays	JSON Objects
Nesting	Yes ('auth' => ['failed' => '...'])	No (flat only)
Comments	Yes (// explanation)	No
Access	trans('messages.welcome')	trans('Welcome')
Loaded by	loadPaths() or loadNamespaced()	loadJsonPaths()

Sources: src/FileLoader.php48-49 src/FileLoader.php110-126

---

Namespaced Translations

Package Namespace Registration

Packages register namespaces via addNamespace() at src/FileLoader.php131-134:

Example:

Package File Structure

vendor/mycompany/mypackage/lang/
├── en/
│ ├── messages.php
│ └── errors.php
└── es/
 ├── messages.php
 └── errors.php

Accessing Namespaced Keys

Use double-colon syntax: namespace::group.key

Override Mechanism

Applications override package translations without modifying vendor files.

Loading Process:

Override File Location:

lang/
└── vendor/
 └── mypackage/
 └── en/
 └── messages.php

Package Original (vendor/mypackage/lang/en/messages.php):

Application Override (lang/vendor/mypackage/en/messages.php):

The loadNamespaced() method at src/FileLoader.php62-71 merges these using array_replace_recursive() at src/FileLoader.php83

Sources: src/FileLoader.php62-71 src/FileLoader.php76-88 src/FileLoader.php131-134

---

Key-to-File Resolution

Translation keys map to file paths and array indices:

Resolution Logic in FileLoader:

Key Format	parseKey() Output	Method Called	File Path
validation.required	group='validation', item='required'	loadPaths() at src/FileLoader.php93	{path}/en/validation.php → $arr['required']
validation.between.numeric	group='validation', item='between.numeric'	loadPaths()	{path}/en/validation.php → $arr['between']['numeric']
Welcome	group='*', item='Welcome'	loadJsonPaths() at src/FileLoader.php110	{path}/en.json → $json['Welcome']
pkg::messages.title	namespace='pkg', group='messages', item='title'	loadNamespaced() at src/FileLoader.php62	{hints['pkg']}/en/messages.php → $arr['title']

Sources: src/FileLoader.php46-57 src/FileLoader.php62-71 src/FileLoader.php93-103 src/FileLoader.php110-126

---

File Organization Patterns

Grouping by Context

Separate translations into logical groups:

lang/en/
├── validation.php # Validation messages
├── auth.php # Authentication/authorization
├── passwords.php # Password reset messages
├── pagination.php # Pagination controls
└── emails.php # Email templates

Key Naming

Use descriptive, consistent key names:

Nesting Depth

Limit nesting to 2-3 levels:

Placeholder Consistency

Maintain identical placeholders across locales:

Sources: lang/en/validation.php1-200

---

Summary

Translation files in the hypervel/translation package follow structured conventions:

• PHP files return arrays and support nesting, comments, and complex structures
• JSON files provide flat key-value mappings for simple use cases
• Directory structure follows {path}/{locale}/{group}.php or {path}/{locale}.json
• Namespaced translations use {hints[namespace]}/{locale}/{group}.php with optional overrides in {path}/vendor/{namespace}/
• The bundled validation file demonstrates real-world best practices
• Placeholders use colon prefix (:placeholder) for dynamic value replacement
• Override mechanism allows applications to customize package translations without modifying source files

The FileLoader class handles all file system operations, loading, and merging of translations according to these conventions.

Sources: src/FileLoader.php1-175 lang/en/validation.php1-197