Skip to main content

Translations — Internal Administration

This page supplements the public Translations documentation with internal details about the translation system, error catalog management, and AI fallback configuration.

Error catalog management​

The static error catalog is maintained in apps/core-api/internal/translations/catalog/. Each country has its own file:

catalog/
├── es_ticketbai.go    # Spain TicketBAI error codes
├── es_verifactu.go    # Spain Verifactu/AEAT error codes
├── es_sii.go          # Spain SII error codes
├── it_sdi.go          # Italy SDI error codes
└── catalog.go         # Registry and lookup logic

Adding a new error code​

  1. Add the error definition to the appropriate catalog file
  2. Include: error_code, original_message, translation, category, severity, retriable, user_message
  3. Run go test ./internal/translations/... to verify
  4. The static catalog takes priority over AI translations

AI fallback configuration​

VariableDefaultDescription
TRANSLATION_AI_ENABLEDtrueEnable AI fallback for unknown errors
TRANSLATION_AI_MODELclaude-3-5-haiku-20241022Claude model for translations
TRANSLATION_AI_CACHE_TTL0 (permanent)Cache duration for AI translations
ANTHROPIC_API_KEYSecret ManagerAPI key for Claude

AI translation caching​

AI translations are cached permanently in the translation_cache table:

CREATE TABLE translation_cache (
  cache_key VARCHAR(255) PRIMARY KEY,  -- hash(error_code + country + system)
  response JSONB NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

Cache invalidation​

To force re-translation of a cached AI response:

DELETE FROM translation_cache WHERE cache_key = '<hash>';

Monitoring​

  • Metric: translation_ai_requests_total — tracks AI fallback usage
  • Alert: translation_ai_error_rate > 10% in 5 minutes
  • Cost tracking: AI translations cost ~$0.001 each; monitor via Anthropic dashboard

Known issues​

  • AI translations for Italian SDI codes occasionally miss regulatory context. Prefer adding them to the static catalog when identified.
  • Rate limiting on Anthropic API applies (tier-dependent). The translation service has its own retry logic with 3 attempts.