Skip to main content

i18n Utilities

The i18n utilities provide translation management and language routing for the Chapinismos dictionary. The system supports Spanish (es) and English (en) locales.

translations

Translation dictionary containing all UI strings for both Spanish and English.
translations
object
Translation object with Spanish (es) and English (en) keys

Structure

const translations: {
  es: Record<string, string>;
  en: Record<string, string>;
}

Available Translation Keys

  • home.title - Page title
  • home.description - Meta description
  • home.keywords - SEO keywords
  • home.subtitle - Hero subtitle
  • home.search.placeholder - Search input placeholder
  • home.featured - Featured words section title
  • home.contribute.* - Contribution section strings
  • home.about.* - About section content
  • search.title - Search page title
  • search.subtitle - Search subtitle
  • search.noResults - No results message
  • search.category.* - Category labels (sustantivo, verbo, adjetivo, etc.)
  • word.definition - Definition label
  • word.examples - Examples section title
  • word.synonyms - Synonyms label
  • word.related - Related words title
  • word.share - Share button text
  • schema.site.* - Site schema data
  • schema.faq.* - FAQ schema templates with variable interpolation

Usage Example

import { translations } from '@/utils/i18n';

const spanishTitle = translations.es['home.title'];
const englishTitle = translations.en['home.title'];

getLangFromUrl

Extracts the language code from a URL pathname.
function getLangFromUrl(url: URL): "es" | "en"

Parameters

url
URL
required
URL object to extract language from

Returns

language
'es' | 'en'
Language code - returns "en" if the URL contains /en/, otherwise defaults to "es"

Example

import { getLangFromUrl } from '@/utils/i18n';

const url1 = new URL('https://chapinismos.org/en/palabras/chucho/');
const lang1 = getLangFromUrl(url1); // "en"

const url2 = new URL('https://chapinismos.org/es/palabras/chucho/');
const lang2 = getLangFromUrl(url2); // "es"

const url3 = new URL('https://chapinismos.org/palabras/chucho/');
const lang3 = getLangFromUrl(url3); // "es" (default)

useTranslations

Creates a translation function for a specific language with variable interpolation support.
function useTranslations(
  lang: string | undefined
): (key: string, vars?: Record<string, string | number>) => string

Parameters

lang
string | undefined
Language code ("es" or "en"). Defaults to "es" for any value other than "en"

Returns

t
function
Translation function that accepts:
  • key (string): Translation key to look up
  • vars (object, optional): Variables to interpolate into the translation string using {variable} syntax
Returns the translated string with interpolated variables, or the key itself if translation is not found.

Example

import { useTranslations } from '@/utils/i18n';

// Basic usage
const t = useTranslations('es');
const title = t('home.title');
// "Chapinismos - Diccionario de Palabras Guatemaltecas"

// With variable interpolation
const t = useTranslations('en');
const subtitle = t('index.subtitle', { count: 150 });
// "Explore all 150 words in the dictionary"

const faqAnswer = t('schema.faq.category.answer', {
  word: 'chucho',
  category: 'sustantivo'
});
// "chucho is a sustantivo used in Guatemala."

Astro Component Usage

---
import { getLangFromUrl, useTranslations } from '@/utils/i18n';

const lang = getLangFromUrl(Astro.url);
const t = useTranslations(lang);
---

<h1>{t('home.title')}</h1>
<p>{t('index.subtitle', { count: allWords.length })}</p>

getLocalizedPath

Generates a localized URL path with the appropriate language prefix.
function getLocalizedPath(path: string, lang: string): string

Parameters

path
string
required
The path to localize (should start with /)
lang
string
required
Language code ("es" or "en")

Returns

localizedPath
string
Path with language prefix: /en{path} for English, /es{path} for Spanish

Example

import { getLocalizedPath } from '@/utils/i18n';

// English path
const enPath = getLocalizedPath('/palabras/chucho/', 'en');
// "/en/palabras/chucho/"

// Spanish path
const esPath = getLocalizedPath('/palabras/chucho/', 'es');
// "/es/palabras/chucho/"

// Navigation example
const currentLang = 'en';
const searchPath = getLocalizedPath('/buscar/', currentLang);
// "/en/buscar/"

Real-World Example

---
import { getLangFromUrl, getLocalizedPath } from '@/utils/i18n';

const lang = getLangFromUrl(Astro.url);
const homePath = getLocalizedPath('/', lang);
const searchPath = getLocalizedPath('/buscar/', lang);
const indexPath = getLocalizedPath('/indice/', lang);
---

<nav>
  <a href={homePath}>Home</a>
  <a href={searchPath}>Search</a>
  <a href={indexPath}>Index</a>
</nav>

Type Definitions

type SupportedLanguage = "es" | "en";

type TranslationKey = 
  | "home.title"
  | "home.description"
  | "search.title"
  | "word.definition"
  // ... and many more

type TranslationVars = Record<string, string | number>;

Build docs developers (and LLMs) love