7. Internationalization on BeamFoundry Rays Core

Message Catalogs & Pluralization

Mon, 01 Jan 0001 00:00:00 +0000

Message Catalogs & Pluralization

Rays simplifies message localization by letting you define translation catalogs directly in your YAML configuration files. Messages are automatically loaded into LocaleMessageBundle instances, with full support for positional parameters, Unicode CLDR pluralization rules, and numeric ranges.

Defining Messages in YAML

Message catalogs are organized by locale under the localization.messages property in your application.yaml file. Rays recognizes four distinct categories of localized messages:

Category	Description	Placeholders
`translation`	Simple string translations. Positional parameters are denoted by `{0}`, `{1}`, `{2}`, etc.	`{0}`, `{1}`, `{2}`, …
`cardinal`	Plural rules determined by item quantities (e.g., “1 day” vs. “5 days”).	`{0}` (the formatted number)
`ordinal`	Plural rules determined by position or rank (e.g., “1st”, “2nd”, “3rd”).	`{0}` (the formatted number)
`ranges`	Plural rules for intervals between two numbers (e.g., “1-3 days”).	`{0}`, `{1}` (the start and end numbers)

Complete YAML Example

localization:
 messages:
 en:
 translation:
 welcome: "Welcome"
 welcome_user: "Welcome, {0} {1}!"
 fields.registration.username: "Username"
 fields.registration.password: "Password"
 fields.registration.confirm: "Confirm Password"
 cardinal:
 days.left:
 ONE: "{0} day remaining"
 OTHER: "{0} days remaining"
 ordinal:
 competition.place:
 ONE: "{0}st place"
 TWO: "{0}nd place"
 FEW: "{0}rd place"
 OTHER: "{0}th place"
 ranges:
 days.range:
 OTHER: "{0}-{1} days"

 fr:
 translation:
 welcome: "Bienvenue"
 welcome_user: "Bienvenue, {0} {1} !"
 fields.registration.username: "Nom d'utilisateur"
 fields.registration.password: "Mot de passe"
 fields.registration.confirm: "Confirmation du mot de passe"
 cardinal:
 days.left:
 ONE: "{0} jour restant"
 OTHER: "{0} jours restants"
 ordinal:
 competition.place:
 ONE: "{0}er prix"
 OTHER: "{0}e prix"
 ranges:
 days.range:
 ONE: "{0}-{1} jour"
 OTHER: "{0}-{1} jours"

CLDR Plural Rules

Different languages follow different rules for pluralization. In English, cardinal numbers only distinguish between ONE (1) and OTHER (0, 2, 3, …). Other languages like Polish, Russian, or Arabic use additional categories such as FEW or MANY.

Container Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Container Configuration

Rays integrates internationalization cleanly into its Inversion of Control (IoC) container. By declaring an i18n Configuration Beam, you can bind YAML configuration properties, configure default and auxiliary locales, load validator translation packs, and publish i18n services for injection throughout your application.

1. Defining Configuration Properties

First, define a struct embedding ConfigurationProperties to bind the localization section from your application.yaml file:

package config

import (
 . "github.com/BeamFoundry/rays/pkg/core"
 . "github.com/BeamFoundry/rays/pkg/i18n"
)

// LocalizationProperties binds messages from application.yaml under "localization".
type LocalizationProperties struct {
 ConfigurationProperties `Name:"localization"`
 messages map[string]LocalizedMessages
}

Rays automatically maps the YAML properties to the internal LocalizedMessages struct containing translation, cardinal, ordinal, and ranges maps.

Web & Template Integration

Mon, 01 Jan 0001 00:00:00 +0000

Web & Template Integration

Internationalized web applications must dynamically determine the user’s preferred language for each incoming HTTP request without requiring developers to manually pass a locale or context parameter through every service, repository, and template call.

Rays solves this using ThreadLocaleContextHolder for request-scoped locale management and LocaleFuncMap for seamless integration with Go’s standard html/template package.

1. Request-Scoped Locale Management

How It Works

ThreadLocaleContextHolder is powered by thread-local storage (routine.ThreadLocal). When an HTTP request enters your application:

Localized Struct Validation

Mon, 01 Jan 0001 00:00:00 +0000

Localized Struct Validation

Web frameworks and API routers typically bind request payloads to structs and validate them using Go-Playground Validator. However, default validation outputs suffer from two major problems:

Error descriptions are in English only.
Field names reflect raw Go struct fields (e.g., "ConfirmPassword" or "user_email") rather than user-friendly UI labels.

Rays’ MessageSourceValidator solves both problems by translating validation rules into the active request locale and replacing field names with localized labels defined in your message catalog.

Predefined Catalogs Reference

Mon, 01 Jan 0001 00:00:00 +0000

Predefined Catalogs Reference

The github.com/BeamFoundry/rays/pkg/i18n/locales package eliminates boilerplate by providing pre-instantiated singletons for standard locales and pre-registered validation translation functions.

Predefined Locales

The Locales struct contains pre-instantiated Go-Playground Locales singletons for over 200 standard language and territory combinations.

Common Locales

import "github.com/BeamFoundry/rays/pkg/i18n/locales"

// English
locales.Locales.EN // English (base)
locales.Locales.EN_US // English (United States)
locales.Locales.EN_GB // English (United Kingdom)
locales.Locales.EN_CA // English (Canada)
locales.Locales.EN_AU // English (Australia)

// French
locales.Locales.FR // French (base)
locales.Locales.FR_FR // French (France)
locales.Locales.FR_CA // French (Canada)
locales.Locales.FR_BE // French (Belgium)
locales.Locales.FR_CH // French (Switzerland)

// German
locales.Locales.DE // German (base)
locales.Locales.DE_DE // German (Germany)
locales.Locales.DE_AT // German (Austria)
locales.Locales.DE_CH // German (Switzerland)

// Spanish
locales.Locales.ES // Spanish (base)
locales.Locales.ES_ES // Spanish (Spain)
locales.Locales.ES_MX // Spanish (Mexico)

// Other European Languages
locales.Locales.IT // Italian
locales.Locales.PT // Portuguese
locales.Locales.PT_BR // Portuguese (Brazil)
locales.Locales.NL // Dutch
locales.Locales.PL // Polish
locales.Locales.RU // Russian
locales.Locales.UK // Ukrainian

// Asian Languages
locales.Locales.JA // Japanese
locales.Locales.KO // Korean
locales.Locales.ZH // Chinese (Simplified)
locales.Locales.ZH_TW // Chinese (Traditional)
locales.Locales.VI // Vietnamese
locales.Locales.TH // Thai
locales.Locales.ID // Indonesian

// Middle Eastern Languages
locales.Locales.AR // Arabic
locales.Locales.FA // Persian / Farsi
locales.Locales.TR // Turkish

Usage with Message Bundles

Pass any Locales singleton to messageSource.NewMessageBundle() or messageSource.FindMessageBundle():