discourse-content-localization

Implements localization models, serializers, and editing UI for Discourse content.

47.8k|9.0k|Updated Jan 12, 2013
One-click install
npx skills add https://github.com/discourse/discourse --skill discourse-content-localization
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: discourse-content-localization
Source: https://github.com/discourse/discourse/tree/main/.skills/discourse-content-localization
Command: npx skills add https://github.com/discourse/discourse --skill discourse-content-localization

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Adding localization support to Discourse models involves many coordinated pieces—database tables, serializers, Guardian checks, preloading, editing UI, and AI backfill jobs—and missing any one of them causes N+1 queries, broken fallbacks, or leaked localization rows.

Core Features & Use Cases

  • Core Model Pattern: Guides adding Localizable models, <Model>Localization tables with LocaleMatchable, unique (model_id, locale) indexes, and get_localization fallback behavior.
  • Hot-Route Safety: Enforces includes(:localizations) preloading on discovery, list, and site JSON routes so serializers never trigger N+1 queries.
  • Editing UI & API Rules: Defines Guardian authorization, server-side param validation, and the rule that edit surfaces show source values rather than localized display values.
  • discourse-ai Boundaries: Keeps AI detection, backfill, and localizer jobs inside plugins/discourse-ai, skipping source-locale and self translations.
  • Use Case: When making Sidebar sections or Groups localizable, follow the checklist to ship the data model, serializer preloading, admin editing UI, and discourse-ai backfill with full test coverage.

Quick Start

Use the discourse-content-localization skill to plan and implement localization support for the Group model including serializers, editing UI, and tests.

Frequently Asked Questions about discourse-content-localization

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I make a Discourse model localizable?

Add `include Localizable` to the source model with a nullable `locale` column, then create a `<Model>Localization` table with `include LocaleMatchable`, translated fields matching source length limits, and a unique `(model_id, locale)` index. Use `get_localization` for fallback behavior instead of reimplementing it in serializers.

How to prevent N+1 queries when serializing localized Discourse content?

Preload localizations with `includes(:localizations)` on every list, boot, site JSON, admin, and controller path that serializes localized fields. Any serializer calling `get_localization` on hot routes like discovery pages must receive records with localizations already preloaded.

Where should AI translation backfill jobs live for Discourse core models?

Automatic detection, backfill, and localizer jobs belong in `plugins/discourse-ai`, never in core. Core holds the data model, serializers, Guardian checks, and edit UI, while discourse-ai adds model-specific Candidate, Localizer, and scheduled backfill jobs.

Why does a localized category settings page show the translated name instead of the source?

Edit and settings surfaces must load source/default values, not localized display values. A Japanese admin opening the "Support" category settings should see the source name "Support", not its localized name, so serializers for edit payloads must return original fields plus localization rows.

Who can edit localizations for Discourse content?

Only users passing a Guardian localization check can edit localizations, enforced server-side. For admin-owned or global content, admin-only checks are preferred, and localization rows are exposed in API responses only to authorized editors.