메뉴
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.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | lingui-next-init |
| 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. |
Initialize Lingui i18n in a Next.js App Router codebase using deterministic templates and a single scaffold script.
Run the scaffold script with an absolute project path:
Set SKILL_ROOT to your actual skill install location first:
.agents/skills/lingui-next-init.claude/skills/lingui-next-initpython3 "${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:
web/src/i18n/layout-factory.tsx and web/src/app/[lang]/(home)/layout.tsx.--server-layouts-package and --server-layouts-version into web/package.json dependencies when missing.web/src/app/[lang]/layout.tsx initLingui flow.initPageLingui(params) in server layouts and server pages before using Lingui t/metadata.Choose one mode:
app-only
Create only app-side files under web/**. Never create packages/i18n.
shared-auto
Detect workspace and existing packages/i18n:
packages/i18n: create shared package templates.packages/i18n: skip creating package files.shared-force
Always render shared package templates under packages/i18n.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.tpl and assets/templates/app-router/web/src/app/[lang]/(home)/layout.tsx.tpl (only when --with-server-layouts is 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:
scriptsdependenciesdevDependencies--with-server-layouts is enabled, add missing dependencies.<server-layouts-package> with <server-layouts-version>Project-root .gitignore is merged incrementally:
web/src/locales/**/*.jsweb/src/locales/**/*.mjsweb/locale/**/*.jsweb/locale/**/*.mjsAfter scaffolding a target project:
First, merge the generated SWC snippet into your Next config:
web/next.swc-snippet.ts into web/next.config.ts.experimental.swcPlugins contains ["@lingui/swc-plugin", {}].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.
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-workflow for 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:init side effect:
pnpm skills:init creates agents/openai.yaml automatically.
If this file is not needed for the new public skill, remove it before finalize.
Large workspace safety:
Run git status before skills:finalize so AD/MM states are understood and not misinterpreted as current-task failures.
Manifest empty:
Confirm web/src/locales/** contains compiled .mjs files, then rerun i18n:manifest.
Locale route mismatch:
Verify web/src/proxy.ts default-locale rewrite and non-default prefix redirect logic.
No translated text at runtime:
Check web/src/i18n/catalog-manifest.ts and web/src/i18n/appRouterI18n.ts loader paths.
Error: Attempted to call a translation function without setting a locale:
Confirm web/src/i18n/initLingui.ts activates locale before setI18n.
Then ensure both server layout.tsx and server page.tsx call initPageLingui(params) (or equivalent) before t/metadata usage.
Prefer useLingui/Trans in shared server components.
shared-auto with existing packages/i18n:
shared-auto will reuse the existing shared package and skip rendering packages/i18n/** templates.
Ensure your package exports <i18n-package-name>/next-config and <i18n-package-name>/lingui-config.
If not, use --mode shared-force to scaffold shared templates or switch to --mode app-only.
withServerLayouts setup issues:
Confirm --with-server-layouts is enabled and your package exports <server-layouts-package>/server.
If you use a custom package, pass --server-layouts-package explicitly.
Read these files only when needed:
references/workflow-app-router.mdreferences/official-notes.mdreferences/pages-router-roadmap.mdskills/lingui-workflowGenerate emoji-prefixed Conventional Commit messages and focused local commits from staged changes or a single clear unstaged change.
Commit a focused local change set with an emoji Conventional Commit message, safely stage a clear unstaged scope when needed, then push the current branch to its remote. Use when the user asks to "commit and push", "commit push", "submit and push", "push my committed change", or wants a local commit finalized on the remote. Do not create pull requests, merge requests, releases, tags, rebases, or deployment changes.
Use this skill when the user wants to decide, set, write, or use a durable coding-agent goal or /goal prompt that keeps Codex, Claude Code, or another agent working until a verifiable done condition is met. It gates autonomy, handles runtime differences, and writes copy-ready goal contracts with outcome, verification, constraints, write boundaries, iteration policy, completion evidence, and pause/ask conditions. Trigger on requests like 'should I set a goal?', 'set up a durable goal', 'give me a /goal prompt', 'turn this vague app idea into a goal', 'keep refactoring until tests pass', 'I am stepping away, have the agent finish this', migrations, refactors, ports, spec implementations, eval loops, backlog cleanup, or multi-checkpoint work. Do not use for single quick edits, running tests once, OKR/scrum goal questions, recurring reminders, or token-budget settings.
Create safe Git feature or hotfix branches with concise names. Use this whenever the user asks to create a branch, start work on a new feature or fix, wants a `feat/...` or `hotfix/...` branch name, asks for a short branch slug from a task description, or wants help before beginning local Git work. Default to recommending the branch name and command first, then create only after user confirmation. Do not push, commit, rebase, or create PRs.
Use when the user's pain is "adding/removing one more X means editing N files" and X is a recurring variant kind: popup, banner, modal, ad slot, payment method, AI model/tool, form field type, connector, sub-site, command, menu item, agent, extension point, or data source. Use when they want to design, refactor, review, name, or explain a pluggable mechanism using registry, interface/trait contract, runtime core, and convention folders; mention pluginize, pluggable, plugin architecture, extension point, registry pattern, or extensibility. Use when explaining the first-principles rationale, DDD/SOLID/OCP mapping, or industry analogies behind that structure. Use for cross-stack mapping to VSCode contributes, Webpack/Vite plugins, Rust/Tauri connectors, Python entry_points, or cargo features. Skip one variant's internals/styles/hooks/copy/bugs, and skip register/registry meaning DI container, user signup, or package registry.
Use BEFORE heavier workflow skills when route choice matters. Route creative work without a design doc/spec to Brainstorm; destructive or hard-to-reverse work to Discuss; unresolved decisions, Plan/Full fan-out, ship checks, unclear bugs, and fresh-eyes fix-then-re-review need this gate. Skip single-line read-only lookups, pure typo/formatting edits, trivial safe one-line fixes, and clearly safe named-skill requests. Outputs Route, Runtime skill, Fallback alias, and Execution path.