facilguide

Lua internationalization utilities for multi-language websites, inspired by the Facil.guide localization architecture.

Facil.guide is a multi-language senior tech guides platform supporting English, Spanish, French, Portuguese, and Italian. This library provides the core i18n building blocks for any Lua web application: locale detection from URL paths, localized path generation, and hreflang tag output for SEO. Works with any Lua web framework or templating engine (OpenResty, Lapis, Lor, Sailor, etc.).

Installation

luarocks install facilguide

Usage

local facilguide = require("facilguide")

-- Detect locale from a URL path
local locale, rest = facilguide.detect_locale("/es/guia/wifi")
-- "es", "/guia/wifi"

local locale2, rest2 = facilguide.detect_locale("/guide/setup")
-- "en", "/guide/setup"  (English is the default)

-- Build localized paths
local path = facilguide.localized_path("fr", "/guide/wifi")
-- "/fr/guide/wifi"

local en_path = facilguide.localized_path("en", "/guide/wifi")
-- "/guide/wifi"  (English has no prefix)

-- Generate hreflang tags for SEO
local tags = facilguide.hreflang_tags("/guide/wifi")
-- <link rel="alternate" hreflang="en" href="https://facil.guide/guide/wifi" />
-- <link rel="alternate" hreflang="es" href="https://facil.guide/es/guide/wifi" />
-- <link rel="alternate" hreflang="fr" href="https://facil.guide/fr/guide/wifi" />
-- <link rel="alternate" hreflang="it" href="https://facil.guide/it/guide/wifi" />
-- <link rel="alternate" hreflang="pt" href="https://facil.guide/pt/guide/wifi" />
-- <link rel="alternate" hreflang="x-default" href="https://facil.guide/guide/wifi" />

-- Check supported locales
local ok = facilguide.is_supported("fr")  -- true
local no = facilguide.is_supported("de")  -- false

-- List all locale codes
local all = facilguide.locales()
-- {"en", "es", "fr", "it", "pt"}

API Reference

facilguide.detect_locale(path)

Detects the locale from a URL path by checking for a two-letter prefix (e.g. /es/, /fr/). Returns the locale code and the remaining path with the prefix stripped. If no recognized locale prefix is found, returns "en" and the original path. English content has no URL prefix by convention.

facilguide.localized_path(locale, path)

Builds a localized URL path by prepending the locale prefix. English paths are returned unchanged (no /en/ prefix). Unrecognized locale codes are ignored and the path is returned as-is. Handles edge cases like root paths and missing leading slashes.

facilguide.hreflang_tags(path, base_url)

Generates a complete set of <link rel="alternate" hreflang="..."> tags for all supported locales plus an x-default entry. Output is a newline-separated string ready for insertion into an HTML <head> section. The base URL defaults to https://facil.guide but can be overridden.

facilguide.locales() / facilguide.is_supported(code)

List all supported locale codes (sorted) or check if a specific code is supported. Currently supports: en, es, fr, it, pt.

License

MIT License. See LICENSE for details.