[codex] Clarify inlang save workflows

[samuelstroschein]

Summary

• document the canonical newProject -> loadProjectInMemory -> project.toBlob() quickstart for creating and saving packed .inlang files
• clarify when to use packed saves vs unpacked saveProjectToDirectory() saves across the getting started, CRUD, unpacked project, writing a tool, and generated README docs
• make saveProjectToDirectory() throw when translation data exists but no exporter plugin is configured, preventing silent empty-directory saves
• make saveProjectToDirectory() accept node:fs as well as node:fs/promises, so load/save examples can use one fs import
• create exporter target directories automatically for plugin pathPattern writes
• update i18next plugin examples to the verified current @6.1.4 version, plus path-resolution notes
• document project.errors.get() and project.close() in plugin and script-style docs
• add a concrete Message Shapes reference for patterns, declarations, selectors, matches, markup, interpolation, and plugin import variants
• fix broken docs query examples and undefined messageId snippets
• add redirects for docs slugs such as /docs/writing-a-tool and /docs/settings-reference

Why

The docs eval showed agents could handle the shallow in-memory quickstart, but broke down around plugin loading, unpacked saves, fs usage, diagnostics, lifecycle, and concrete message shapes. The worst failure was silent data loss when saving translation data to an unpacked directory without an exporter plugin. This PR makes the current docs path runnable and explicit for those deeper workflows.

Validation

• pnpm view @inlang/plugin-i18next version -> 6.1.4
• pnpm --filter @inlang/sdk test
• pnpm --filter @inlang/sdk build
• pnpm --filter @inlang/plugin-i18next test
• git diff --check

pnpm --filter @inlang/website-v2 lint was attempted earlier, but the current worktree is missing generated/site type setup such as src/router.tsx's routeTree.gen and marketplace workspace package type declarations, so it could not isolate this change.

---

Note

Medium Risk
Behavioral change in saveProjectToDirectory() (now throws and changes fs-module expectations) could break existing callers or scripts that relied on previous no-op/unwritten export behavior, but the change is localized and covered by new tests.

Overview
Updates docs/README copy across the repo to position .inlang as the canonical SQLite-based project file (with version control via lix), and to clearly distinguish packed saves (project.toBlob()) from the Git-friendly unpacked directory plus plugin-driven import/export (including guidance to check project.errors.get() and to project.close()). It also adds a new Message Shapes reference page and updates plugin examples (notably i18next) and docs routing aliases/redirects.

Hardens @inlang/sdk’s saveProjectToDirectory() by accepting both node:fs and node:fs/promises, auto-creating exporter target directories for pathPattern outputs, and throwing when translation data exists but no exporter plugin is configured (preventing silent “empty” unpacked saves); tests are added for these behaviors.

^{Reviewed by Cursor Bugbot for commit cfa52ff. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: cfa52ff

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
@inlang/sdk	Patch
@inlang/cli	Patch
@inlang/plugin-i18next	Patch
@inlang/plugin-m-function-matcher	Patch
@inlang/plugin-t-function-matcher	Patch
@inlang/rpc	Patch
@inlang/editor-component	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	inlang-website	ac3f7c4	Commit Preview URL Branch Preview URL	Apr 29 2026, 04:11 AM