Skip to content

rgglez/rgglez-dev-skills / plugins/astro-mdx-localization/skills/astro-mdx-localization

astro-mdx-localization

Verified

Translate or update localized Markdown and MDX content in Astro projects while preserving content identity, executable examples, components, assets, and locale navigation. Use when a source article and target locale are provided or inferable from the request.

Astro MDX localization

Translate the requested content using the project's own localization model. Support any source and target languages; do not assume a particular theme, directory layout, package manager, or hosting provider.

Discover the project conventions

Before writing the translation, inspect:

  • The source file, any existing target translation, and a nearby localized article. An existing target may contain edits worth preserving.
  • Applicable repository instructions and the content collection schema or loader. Locate these within the actual Astro application, which may be in a monorepo subdirectory.
  • The routing and translation lookup used by this content. Determine whether translations share a filename, an explicit identifier, a slug, or another key. Do not assume filenames and slugs serve the same purpose.
  • The application package scripts, package manager, formatter configuration, and Markdown/MDX plugins, including generated table-of-contents behavior.

Use this evidence to determine the destination, localized URL, metadata fields, and validation commands. Ask only if the target language or a consequential convention remains ambiguous. Create only the requested locales.

Preserve identity and meaning

  • Preserve the article's scope, structure, technical claims, qualifications, numbers, and versions. Translate naturally without adding new material. If the source appears incorrect, report the issue separately rather than silently revising it as part of translation.
  • Translate reader-facing titles, descriptions, headings, prose, table cells, image alt text, captions, and component labels.
  • Set the locale and localize the slug only as required by the project's schema and routing. Keep the established translation key intact. A shared filename is mandatory only when the project uses it to link translations.
  • Preserve authorship, dates, publication flags, and machine-readable metadata unless the request or project conventions require changes. Translate descriptive tags only when the tag taxonomy supports it. Do not invent fields or mechanically translate identifiers, license names, or enum values.
  • Reuse existing assets. Preserve the resolved asset targets; adjust relative paths if the destination depth changes. Keep working aliases and imports. Generate or replace images only when requested.

Keep examples and MDX functional

  • Preserve executable commands, options, filenames, identifiers, environment variables, API names, hashes, and technical output. Translate explanatory code comments when appropriate.
  • Translate user-facing strings in a provided script only when they are not protocol values or otherwise consumed by code. Keep matching sample output and troubleshooting text consistent. Preserve verbatim diagnostic messages emitted by external tools. Do not run article commands merely to translate them: they may install software, modify data, or contact services.
  • Preserve JSX/component names, imports, expressions, and functional props. Translate textual props according to their meaning, not all strings blindly. Maintain whitespace needed for Markdown inside components to render.
  • Keep source and external links unless an authoritative localized equivalent is known. For internal links, verify that the target locale page actually exists before changing its URL. Follow the site's fallback behavior when it does not; do not invent routes.
  • Follow the project's HTML-versus-Markdown link convention. Avoid angle-bracket URL autolinks that the MDX parser treats as JSX. Check that formatting has not split an inline link into a separate paragraph.
  • If the table of contents is generated, use the heading recognized for the target locale; do not also write a manual list. Check localized anchor links against generated heading IDs. If a new locale needs routing or plugin configuration, identify that requirement and keep changes within the task's authorized scope.

Validate and report

  1. Review source and target side by side for omitted paragraphs, changed meaning, broken components, missing links, and unintended code changes. Compare code blocks with allowances for deliberately translated comments and messages; byte-for-byte equality is not sufficient on its own.
  2. Format only the changed files using the project's configured formatter from the application directory. Review its changes, especially JSX and inline links. In a Git checkout, check whitespace and the final diff, including newly created files, without changing unrelated work.
  3. Run the existing build or relevant content validation using the declared package manager. Do not assume a fixed executable path or install a new toolchain merely because a command is missing. Distinguish content errors from environment restrictions; request permitted access when needed instead of changing valid source to accommodate the sandbox.
  4. Inspect the generated page or available preview for translated metadata, heading/TOC rendering, asset resolution, and links between locales where the site provides them. Do not assume a fixed build output directory or that all routes produce static HTML. Run a search-index check only if the project includes one in its workflow.

Report the destination, localized URL when verified, completed checks, and any remaining validation limits. Do not describe retained verification dates in the article as tests performed during the translation task.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall