docs: add "Use Locize for translation management" recipe

[adrai]

Heads-up — CONTRIBUTING.md asks for an Issue first for larger contributions. I'm opening this as a direct PR rather than an Issue because the material is already drafted (155 lines, 1 new file, additions-only) and easier to evaluate as code than as prose. Happy to convert this to an Issue or Discussion if you'd prefer that path — I'll close this PR immediately on your signal. Or if it's not a fit at all (e.g. you'd rather keep TMS recommendations out of /recipes/ and link only via the "Community libraries" entry on the existing i18n recipe), that's also a fine answer.

---

Adds a new src/content/docs/en/recipes/use-with-locize.mdx recipe documenting how to sync translations from Locize at build time using locize-cli, alongside Astro's built-in i18n routing.

Locize is a translation management system created by the maintainers of i18next. It supports the i18next JSON v4 format natively, so the integration with Astro is build-time-only — locize-cli downloads the latest published JSON into src/i18n/locales/{lng}/{ns}.json, and a small useTranslations(lang) helper (same pattern as the existing i18n recipe) layers a t() function on top.

The recipe covers, via <Steps>:

1. Install locize-cli (with PackageManagerTabs for npm/pnpm/yarn)
2. Add downloadLocales + syncLocales scripts to package.json, with a :::note documenting Locize's two CDN endpoints (Standard at api.lite.locize.app, Pro at api.locize.app)
3. Run npm run downloadLocales and the resulting FileTree
4. Assemble the namespaced JSON into a flat lookup tree in src/i18n/ui.ts
5. Write the useTranslations helper in src/i18n/utils.ts (same pattern as your existing i18n recipe, extended with {name}-style interpolation)
6. Use the helper from a [lang]/index.astro page with getStaticPaths

Plus a "Pushing new keys back to Locize" section covering the three workflows (locize sync, i18next-cli static extraction, the Locize web app), and a note that runtime saveMissing / live CDN fetch / in-context editing belong inside framework islands via @astrojs/<framework> — not the static layer.

Frontmatter uses i18nReady: true and type: recipe per the convention in external-links.mdx and analyze-bundle-size.mdx.

Companion assets (in case useful for evaluation): runnable Astro 6 + Locize example repo and a step-by-step blog walkthrough.

Sidebar entry appears automatically alongside the other recipes via the existing /recipes/ index.

Happy to adjust scope, wording, code-block style, or sidebar placement if a different shape would land better — or, again, to convert this to an Issue if that's the preferred entry point.

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	ca46693
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6a0da9dea77a510008892276
😎 Deploy Preview	https://deploy-preview-13916--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/recipes/use-with-locize.mdx	Localization added, will be marked as complete.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[astrobot-houston]

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any broken links you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.

[Copilot]

Pull request overview

Adds a new Starlight recipe documenting how to use Locize + locize-cli to download i18n JSON files at build time and wire them into a useTranslations() helper compatible with Astro’s built-in i18n routing.

Changes:

• Adds a new /recipes/ MDX page with end-to-end setup steps for locize-cli (download + sync).
• Documents a simple ui.ts flattening approach and a useTranslations(lang) helper with interpolation.
• Includes guidance/resources for pushing new keys back to Locize.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ArmandPhilippot]

Thank you for your contribution even if it doesn't follow either our CONTRIBUTING guide or our PR template...

We encourage you to:

• File an Issue to let us know of outdated, confusing, or incorrect documentation. You can also let us know of any problems you encounter on the site itself.
• Start a Discussion if you're not sure that your "issue" rises to the level of incorrect documentation requiring a "fix," but you still want to share ideas and opinions.
• Make a PR directly for very obvious documentation fixes like typos or broken links.

This should have been a discussion, not a PR.

But, anyway, our recipes are meant to walk a reader through completing a working example of a specific task with Astro itself.

We don't have the bandwidth to maintain recipes for Astro + X third-party service, with the exception of highly popular tools such as Tailwind because our users ask for it. Hence the importance of a discussion to gauge interest.

link only via the "Community libraries" entry on the existing i18n recipe)

This is also not an option unfortunately. We used to do that in the past, but in #13003 we decided to stop to avoid broken links and to only link to our integrations catalog.

So, I'm afraid we can't accept this. But, it could be a great content on Locize docs itself in a section explaining how to integrate Locize with third party frameworks or even a blog post. Then, you could submit this as an external resource to Astro Tips. You can also promote the guide in our #showcase channel in Discord.

[adrai]

Thank you for the clear and honest reasoning — completely understood, and apologies for skipping the Discussion step. I appreciate you taking the time to explain both the scoping rule (recipes for Astro itself, not third-party integrations) and the #13003 precedent on Community-libraries linking.

Closing this PR now. I'll explore the Astro Tips external resources submission path and the #showcase Discord channel as you suggested — those feel like the right surfaces for this kind of content.

Thanks again!