Overview

The hypervel/translation package provides internationalization (i18n) functionality for Hyperf applications. This page describes the package's architecture, core components, dependencies, and integration with the Hyperf framework.

Related Pages:

• Core Translation System (page 2) - Translator class internals
• Global Helper Functions (page 3) - __(), trans(), trans_choice()
• Configuration and Dependency Injection (page 6) - ConfigProvider and factory setup

Purpose and Scope

The hypervel/translation package implements a translation system for Hyperf applications. It provides Laravel-compatible APIs while integrating with Hyperf's coroutine context system.

Core Features:

• PHP array and JSON translation file loading via FileLoader
• Pluralization through MessageSelector class
• Namespace-based organization (e.g., package::group.key)
• Lazy translation via PotentiallyTranslatedString
• Runtime translation addition through ArrayLoader
• Global functions: __(), trans(), trans_choice()

Package Identity:

• Name: hypervel/translation
• Type: library
• License: MIT
• Repository: https://github.com/hypervel/translation

Sources: composer.json1-11 README.md1-3

System Architecture

The package architecture separates concerns across five layers: public API, core translation engine, data loading, configuration/DI, and framework integration.

Component Structure with Code Entities

Layer Responsibilities:

Layer	Components	Purpose
Public API	__(), trans(), trans_choice()	Entry points from src/Functions.php14-46
Contracts	Translator, Loader, HasLocalePreference	Interface definitions for loose coupling
Core Engine	Translator, MessageSelector, PotentiallyTranslatedString	Translation logic and pluralization
Loaders	FileLoader, ArrayLoader	Translation data retrieval
DI Setup	ConfigProvider, TranslatorFactory, LoaderFactory	Container registration

Sources: src/Functions.php1-47 src/Translator.php1-73 composer.json23-29 composer.json40-43

Dependencies and Requirements

The package requires PHP 8.2+ and integrates with Hyperf framework components.

Required Dependencies

Dependency	Version Constraint	Used By
php	^8.2	All components
hyperf/contract	~3.1.0	Translator, ConfigProvider
hypervel/filesystem	^0.3	FileLoader
hypervel/support	^0.3	Translator, MessageSelector

Dependency Graph

Key Integrations:

• Translator extends Hypervel\Support\NamespacedItemResolver for key parsing src/Translator.php19
• Translator implements Hyperf\Contract\TranslatorInterface (via Contracts\Translator)
• FileLoader uses Hypervel\Filesystem\Filesystem for file operations
• MessageSelector uses Hypervel\Support\Str for string manipulation

Sources: composer.json31-36 src/Translator.php1-19

Core Components

The package contains seven primary components that handle translation requests from application code.

Translation Request Flow

Component Responsibilities Table

Component	File Location	Primary Responsibility	Key Methods
Translator	src/Translator.php19-505	Orchestrates translation retrieval, caching, locale management	get(), choice(), setLocale()
MessageSelector	src/MessageSelector.php	Implements pluralization rules	choose()
FileLoader	src/FileLoader.php	Loads PHP/JSON translation files from disk	load(), addNamespace()
ArrayLoader	src/ArrayLoader.php	Stores translations in memory	load(), addMessages()
PotentiallyTranslatedString	src/PotentiallyTranslatedString.php	Defers translation until string conversion	__toString()
ConfigProvider	src/ConfigProvider.php	Registers DI bindings	__invoke()
Global Functions	src/Functions.php14-46	Provides convenience access	__(), trans(), trans_choice()

Component Interactions:

• Translator uses Loader contract for data retrieval (polymorphic: FileLoader or ArrayLoader)
• Translator delegates pluralization to MessageSelector src/Translator.php186
• Translator extends NamespacedItemResolver for key parsing src/Translator.php19
• Translator stores locale in Hyperf\Context\Context src/Translator.php432-433
• Global functions retrieve Translator from DI container src/Functions.php16-18

Sources: src/Translator.php1-505 src/Functions.php1-47

Package Structure and Autoloading

The library follows PSR-4 autoloading standards with a clear namespace organization and automatic function loading.

Autoloading Configuration

The package uses a dual autoloading approach:

1. PSR-4 Class Autoloading: All classes under Hypervel\Translation\ namespace map to the src/ directory
2. Global Function Loading: Translation helper functions are automatically loaded from src/Functions.php

Hyperf Integration

The library integrates with Hyperf through the ConfigProvider pattern, automatically registering all necessary services and contracts with the dependency injection container.

Integration Features:

• Automatic service registration via ConfigProvider
• Contract-based dependency injection
• Factory pattern for complex object creation
• Context-aware locale management
• Coroutine-safe translation caching

Sources: composer.json23-29 composer.json40-47