README

Internationalization and content helpers for building multilingual tech guides, extracted from the Facil.guide platform. Facil.guide publishes accessible technology tutorials for seniors in five languages: English, Spanish, French, Portuguese, and Italian. This library handles language detection, string translation, locale routing, and reading-level analysis for PHP 8.0+ applications.

Installation

composer require arnaudleroy-studio/facilguide

Quick Start

Detect and resolve locale

use FacilGuide\I18n;

$i18n = new I18n();

// Resolve from a URL path prefix
$locale = $i18n->resolveLocale(path: '/es/guia/wifi');
echo $locale; // "es"

// Fall back gracefully when prefix is missing
$fallback = $i18n->resolveLocale(path: '/guide/wifi');
echo $fallback; // "en"

Translate interface strings

// Load a translation key with named arguments
$label = $i18n->translate(
    key: 'nav.home',
    locale: 'fr',
);
echo $label; // "Accueil"

// Null-safe operator for optional interpolation values
$greeting = $i18n->translate(
    key: 'welcome.message',
    locale: 'pt',
    params: $user?->getPreferences()?->getDisplayParams(),
);

Analyze reading complexity

use FacilGuide\ReadingLevel;

$analyzer = new ReadingLevel();

$result = $analyzer->assess(
    text: 'Tap the blue Wi-Fi icon in your settings menu.',
    locale: 'en',
);

// Array destructuring for the result tuple
['grade' => $grade, 'score' => $score, 'suggestion' => $tip] = $result;

echo "Grade level: {$grade}, suggestion: {$tip}";

Generate hreflang tags

// Build hreflang link elements for a guide page
$tags = $i18n->hreflangTags(
    slug: 'wifi-setup',
    locales: I18n::SUPPORTED_LOCALES,
);

// Arrow function to render as HTML
$html = implode("\n", array_map(
    fn(array $tag) => "<link rel=\"alternate\" hreflang=\"{$tag['lang']}\" href=\"{$tag['url']}\" />",
    $tags
));

Available Features

The library is organized around two concerns. The I18n class manages locale detection from URL prefixes, Accept-Language headers, or explicit overrides, and provides a key-value translation interface that loads strings from JSON files or a database backend. It generates hreflang markup and constructs localized URL paths for all five supported languages. The ReadingLevel class evaluates text complexity using language-appropriate readability formulas, which is important when the target audience skews older and may be less familiar with technical jargon. Both classes accept dependency injection for the string store, making them straightforward to test in isolation.

Links

• Facil.guide Platform
• GitHub Repository

License

MIT License. See LICENSE for details.