lingui-next-init
GitHub为 Next.js App Router 项目初始化 Lingui i18n，支持单项目或 monorepo。通过确定性脚本生成配置与模板，提供 app-only、shared-auto、shared-force 多种模式，并可选集成服务端布局。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill lingui-next-init -g -y
SKILL.md
Frontmatter
{
"name": "lingui-next-init",
"metadata": {
"author": "adonis"
},
"description": "Scaffold Lingui i18n for Next.js App Router projects with deterministic scripts and templates. Use when you need to initialize or standardize multilingual setup in a single project or monorepo."
}
Lingui Next Init
Initialize Lingui i18n in a Next.js App Router codebase using deterministic templates and a single scaffold script.
Quick Start
Run the scaffold script with an absolute project path:
Set SKILL_ROOT to your actual skill install location first:
- Repository development:
.agents/skills/lingui-next-init - Installed runtime location:
.claude/skills/lingui-next-init
python3 "${SKILL_ROOT}/scripts/scaffold_lingui_next.py" \
--project-root /abs/path/to/project \
--mode app-only \
--locales en,zh \
--default-locale en \
--source-locale en \
--package-manager pnpm
Dry-run first:
python3 "${SKILL_ROOT}/scripts/scaffold_lingui_next.py" \
--project-root /abs/path/to/project \
--mode shared-auto \
--locales en,zh \
--default-locale en \
--source-locale en \
--package-manager pnpm \
--dry-run
--package-manager is restricted to: pnpm, npm, yarn, bun.
Optional server-layout composition:
python3 "${SKILL_ROOT}/scripts/scaffold_lingui_next.py" \
--project-root /abs/path/to/project \
--mode app-only \
--locales en,zh \
--default-locale en \
--source-locale en \
--package-manager pnpm \
--with-server-layouts \
--server-layouts-package @adonis-kit/react-layouts \
--server-layouts-version latest \
--dry-run
When --with-server-layouts is enabled:
- Render optional templates:
web/src/i18n/layout-factory.tsxandweb/src/app/[lang]/(home)/layout.tsx. - Merge
--server-layouts-packageand--server-layouts-versionintoweb/package.jsondependencieswhen missing. - Preserve the default
web/src/app/[lang]/layout.tsxinitLinguiflow. - Keep server initialization explicit: call
initPageLingui(params)in server layouts and server pages before using Linguit/metadata.
Mode Decision
Choose one mode:
-
app-onlyCreate only app-side files underweb/**. Never createpackages/i18n. -
shared-autoDetect workspace and existingpackages/i18n:
- Workspace + missing
packages/i18n: create shared package templates. - Existing
packages/i18n: skip creating package files. - No workspace and no package: fallback to app-only behavior.
shared-forceAlways render shared package templates underpackages/i18n.
Generated Scope
The script renders templates from:
assets/templates/app-router/web/**.tplassets/templates/app-router/packages/i18n/**.tpl(mode-dependent)assets/templates/app-router/web/src/i18n/layout-factory.tsx.tplandassets/templates/app-router/web/src/app/[lang]/(home)/layout.tsx.tpl(only when--with-server-layoutsis enabled)assets/templates/pages-router/_reserved.tpl(reserved for future extension, not scaffolded)
web/package.scripts.json.tpl is merged into web/package.json incrementally:
- Add missing
scripts - Add missing
dependencies - Add missing
devDependencies - If
--with-server-layoutsis enabled, add missingdependencies.<server-layouts-package>with<server-layouts-version> - Never overwrite existing keys
Project-root .gitignore is merged incrementally:
- Add missing compiled-catalog ignore patterns:
web/src/locales/**/*.jsweb/src/locales/**/*.mjsweb/locale/**/*.jsweb/locale/**/*.mjs
- Never remove existing rules
Validation Workflow
After scaffolding a target project:
First, merge the generated SWC snippet into your Next config:
- Merge
web/next.swc-snippet.tsintoweb/next.config.ts. - Ensure
experimental.swcPluginscontains["@lingui/swc-plugin", {}]. - Without this step, Lingui extraction/compile behavior may not match expectations.
pnpm --filter @your/web run i18n:extract
pnpm --filter @your/web run i18n:compile
pnpm --filter @your/web run i18n:manifest
pnpm --filter @your/web run typecheck
Use --fill-source when placeholder translation is acceptable:
pnpm --filter @your/web run i18n:translate -- --fill-source
Daily command execution and troubleshooting are maintained in lingui-workflow.
Use skills/lingui-workflow for the day-to-day extract/translate/compile workflow.
Experience Notes
Use this checklist to avoid common maintenance mistakes when updating Lingui skills:
-
Handoff timing: After scaffold/setup is done, hand over immediately to
skills/lingui-workflowfor day-to-day command guidance. -
Documentation migration order: Migrate content to the target new doc first, then delete old duplicate docs, and run finalize pipeline last.
-
skills:initside effect:pnpm skills:initcreatesagents/openai.yamlautomatically. If this file is not needed for the new public skill, remove it before finalize. -
Large workspace safety: Run
git statusbeforeskills:finalizesoAD/MMstates are understood and not misinterpreted as current-task failures.
Troubleshooting
-
Manifest empty: Confirm
web/src/locales/**contains compiled.mjsfiles, then reruni18n:manifest. -
Locale route mismatch: Verify
web/src/proxy.tsdefault-locale rewrite and non-default prefix redirect logic. -
No translated text at runtime: Check
web/src/i18n/catalog-manifest.tsandweb/src/i18n/appRouterI18n.tsloader paths. -
Error:
Attempted to call a translation function without setting a locale: Confirmweb/src/i18n/initLingui.tsactivates locale beforesetI18n. Then ensure both serverlayout.tsxand serverpage.tsxcallinitPageLingui(params)(or equivalent) beforet/metadata usage. PreferuseLingui/Transin shared server components. -
shared-autowith existingpackages/i18n:shared-autowill reuse the existing shared package and skip renderingpackages/i18n/**templates. Ensure your package exports<i18n-package-name>/next-configand<i18n-package-name>/lingui-config. If not, use--mode shared-forceto scaffold shared templates or switch to--mode app-only. -
withServerLayoutssetup issues: Confirm--with-server-layoutsis enabled and your package exports<server-layouts-package>/server. If you use a custom package, pass--server-layouts-packageexplicitly.
References
Read these files only when needed:
references/workflow-app-router.mdreferences/official-notes.mdreferences/pages-router-roadmap.md- Daily workflow skill:
skills/lingui-workflow
Version History
- e0220ca Current 2026-07-05 23:29
