feat: Complete L10n infrastructure implementation #366
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add complete L10N.md developer guide covering all modes, CLI usage, and workflows - Update README.md with clear quick start and pnpm targets - Update template.env with new L10N_ variable names and CI defaults - Clarify l10n vs translation terminology throughout
✅ Deploy Preview for pauseai ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Collaborator
Author
|
I'm going to be changing development and CI/CD to be able to run almost the same build. Local builds will continue to filter noise from logs but the CI/CD ones won't, for now. The first little commit allows that to work. |
…ose mode - Remove illegal `return` statement at ES module top level that caused SyntaxError - Wrap main filtering logic in `else` block to prevent duplication when --verbose is used - Fixes CI/CD build failures when --verbose flag is present in command line arguments 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
Prevents accidental writes to production l10n cage from local development while supporting CI/CD workflows. Implements dynamic branch detection with fallbacks: - L10N_BRANCH environment override - CI environment detection (Netlify PR previews, branch deploys) - Current git branch as fallback Key safety features: - Blocks local development writes to main cage branch - Tests git authentication upfront to prevent failed commits - SSH auto-detection and switching for easier Git operations - CI environments error rather than fall back to dry-run with e.g. invalid API keys - Automatic branch creation and upstream tracking - Comprehensive test coverage (114 test lines) See L10N.md "Branch Safety System" section for usage. A later commit will integrate the new feature.
Collaborator
Author
|
Cool. I should note, I have seen each of these same commits build here under CI/CD with all locales enabled too (on the l10-preview branch). I'm pushing them into the pull request individually to see them working for en-only too before we merge into main. |
added 4 commits
June 13, 2025 02:47
Creates the Mode class implementing the three l10n operating modes: - en-only: No l10ns bothered, maximum speed (default for local dev) - dry-run: Uses captured l10ns only, no LLM calls (missing API key or --dry-run flag) - perform: Prompts LLMs to capture new l10ns into cage (valid API key + proper branch) Key features: - Centralized mode determination replacing scattered logic - Dropped dry-run based on isDev in favor of explicit API key env choice - Safe defaults prevent expensive operations in development - Clear mode announcements via mode.announce() - Branch safety integration for perform mode validation - Comprehensive test coverage (295 test lines, 100% coverage) See L10N.md "L10n Modes" section for behavior details. A later commit will integrate this as yet unused new feature.
Enables selective retranslation of specific files using familiar glob patterns.
Supports standard minimatch syntax including wildcards, character classes, and brace expansion.
Usage examples:
- `pnpm l10n --force "*.md"` - All markdown files
- `pnpm l10n --force "2024-*"` - Files with specific prefix
- `pnpm l10n --force "{join,donate}.md"` - Multiple specific files
- `pnpm l10n --force en.json proposal.md` - Mixed file types
Key features:
- Clean module extraction in force.ts with resolve() function
- Comprehensive help system with examples and syntax guide
- Integration tests against real filesystem (143 test lines)
- Proper CLI argument parsing (fixed minimist boolean handling)
See L10N.md "Force Mode Patterns" section for complete syntax guide.
This as yet unused new feature will be integrated in a later commit.
…hanges) Migrates from "translation" to "l10n" terminology with strategic commit splitting to preserve git file history. Renames core files and directory structure: Directory migration: - scripts/translation/ → scripts/l10n/ Key file renames: - translate.ts → run.ts (main entry point) - translate-core.ts → heart.ts (core l10n logic) - Keep git-ops.ts, prompts.ts, utils.ts, etc. Limited terminology updates in moved files to ensure git detects renames. Note: This intermediate state does not build - completed in next commit. Part of comprehensive terminology migration to "l10n cage" architecture. See L10N.md for the new terminology and concepts.
…features As noted, this applies large changes to already moved git-ops, heart and run; also appropriately changes other files outside of scripts/l10n. Completes the transition from "translation" to "l10n cage" architecture with full integration of the new Mode, Branch Safety, and Force systems. Terminology migration: - Function names: translate() → l10nFromLLM(), translateOrLoad*() → retrieve*() - Parameter names: languageTag → locale, translationOptions → options - Type names: TranslationOptions → Options, TargetStrategy → Targeting - Comments and documentation: Complete "l10n cage" terminology throughout - Environment variables: Uses L10N_OPENROUTER_API_KEY, L10N_BRANCH Feature integration: - Mode system: Integrated in run.ts with mode.announce() and safe defaults - Branch safety: Integrated l10nCageBranch() and pushWithUpstream() - Force mode: Added resolveForcePatterns() and --force CLI support CLI simplification: - Removed redundant pnpm scripts (l10n:dry-run, l10n:estimate, etc.) - Unified to `pnpm l10n` with --dry-run, --force, --verbose flags - Updated dev/build integration for automatic l10n invocation Environment improvements: - isDev() now uses CI detection instead of NODE_ENV for consistent local defaults - Cache location: l10n-cage/ replaces src/temp/translations/ - Package: Added minimatch dependency for glob pattern support See L10N.md for complete documentation of new architecture.
Collaborator
Author
|
The next two commits (together performing a terminology migration and using the features committed already) come as a pair only to try to maintain as much rename history as possible while changing a lot of content. If it gets lost, so be it. Point is: things build before they appear. Things should build/work on CI/CD after the pair appears. That's what I'll check. |
Collaborator
|
Looks good to me at first glance, i'll take a closer look later |
Remove some duplication and make more prominent upfront that for the most part you should let the CI/CD feed the l10ns.
People might feel obliged to read the whole thing carefully. Unless they are actually developing the l10n system itself, they do not! Let the CI/CD feed the l10ns.
Wituareard
reviewed
Jun 13, 2025
Wituareard
reviewed
Jun 13, 2025
Collaborator
|
The rest looks good |
Collaborator
|
The GitHub Action needs a command that does as little as possible other than compiling a Paraglide runtime. It currently uses |
Collaborator
Author
|
Oh, right. Without digging myself I lazily ask - where/how is the action to
be triggered defined?
Absolutely fine to reintroduce the target if needed, but I'd name it after
its client?
…On Sat, 14 Jun 2025, 18:27 Wituareard, ***@***.***> wrote:
*Wituareard* left a comment (PauseAI/pauseai-website#366)
<#366 (comment)>
The GitHub Action needs a command that does as little as possible other
than compiling a Paraglide runtime. It currently uses inlang:settings and
I can't find something similar
—
Reply to this email directly, view it on GitHub
<#366 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAXXDPXBMHMET2RROKAY6L3DRLORAVCNFSM6AAAAAB7G2EXGCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSNZSHA4TKOBTGY>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
Collaborator
|
.github/workflows/pnpm-check.yml |
Collaborator
Author
|
Oh, right. So I hadn't found it because it's new in main today, but
certainly looks like a sane addition.
By all means just put the target back on the PR branch.
…--Anthony.
On Sat, 14 Jun 2025, 20:59 Wituareard, ***@***.***> wrote:
*Wituareard* left a comment (PauseAI/pauseai-website#366)
<#366 (comment)>
.github/workflows/pnpm-check.yml
—
Reply to this email directly, view it on GitHub
<#366 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAXXDNULPJSFGOOARG2WSD3DR5IDAVCNFSM6AAAAAB7G2EXGCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSNZTGEYTSMJQG4>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
Collaborator
|
oops, accidentally rebased, sorry |
Wituareard
force-pushed
the
l10n-infrastructure-complete
branch
2 times, most recently
from
9a98f83 to
0f7f1ef
Compare
Collaborator
|
my git config is messed up, idk what's going on, won't try to merge again |
Collaborator
Author
|
Commiserations.
Thanks for saying and thus making space not to conflict!
I'll progress it.
…On Sun, 15 Jun 2025, 13:18 Wituareard, ***@***.***> wrote:
*Wituareard* left a comment (PauseAI/pauseai-website#366)
<#366 (comment)>
my git config is messed up, idk what's going on, won't try to merge again
—
Reply to this email directly, view it on GitHub
<#366 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAXXDMWWWUXIVO4LL7MP5D3DVQADAVCNFSM6AAAAAB7G2EXGCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSNZTG42DMNRUG4>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
Collaborator
Author
|
I mean, I think this is a case where Claude added some value. Let's check
with you though. Did you actually want to merge the PR into main, or were
you just getting it ready to do that after other review or comments from
others?
Analysis of the Issue
Your co-developer tried to update the PR with the 10 new commits from
main but rebasing was confusing. The "pushed 10 commits" then "pushed
0 commits" pattern shows he was attempting to rebase then undoing it.
Current status:
- ✅ PR is CLEAN and MERGEABLE on GitHub
- ✅ The inlang:settings target was successfully added
-
… Commiserations.
Thanks for saying and thus making space not to conflict!
I'll progress it.
On Sun, 15 Jun 2025, 13:18 Wituareard, ***@***.***> wrote:
> *Wituareard* left a comment (PauseAI/pauseai-website#366)
> <#366 (comment)>
>
> my git config is messed up, idk what's going on, won't try to merge again
>
> —
> Reply to this email directly, view it on GitHub
> <#366 (comment)>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AAAXXDMWWWUXIVO4LL7MP5D3DVQADAVCNFSM6AAAAAB7G2EXGCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSNZTG42DMNRUG4>
> .
> You are receiving this because you authored the thread.Message ID:
> ***@***.***>
>
|
Collaborator
Author
|
Oh, and I think the typescript error in runtime.js was itself my fault! I
fiddled with isServer re Deno and edge functions.
Fixing it properly!
(But lmk your thoughts re merging.)
…On Sun, 15 Jun 2025, 15:58 Anthony Bailey, ***@***.***> wrote:
I mean, I think this is a case where Claude added some value. Let's check
with you though. Did you actually want to merge the PR into main, or were
you just getting it ready to do that after other review or comments from
others?
Analysis of the Issue
Your co-developer tried to update the PR with the 10 new commits from
main but rebasing was confusing. The "pushed 10 commits" then "pushed
0 commits" pattern shows he was attempting to rebase then undoing it.
Current status:
- ✅ PR is CLEAN and MERGEABLE on GitHub
- ✅ The inlang:settings target was successfully added
-
|
Collaborator
|
Uhh I just wanted to merge the TS fixed from main here but accidentally rebased them on top of the PR commits. And how did you modify runtime.js? Does the script process the output of the paraglide compilation result? |
…nfrastructure-complete
Collaborator
Author
|
No, check inlang-settings - the compiler let's you patch code.
I hope all is clear if you read the commit I pushed without issue to main.
Yes, I've merged it into the PR now.
I understand status: will wait for further PR review and sign-off.
Thanks for engaging!
…On Sun, 15 Jun 2025, 17:12 Wituareard, ***@***.***> wrote:
*Wituareard* left a comment (PauseAI/pauseai-website#366)
<#366 (comment)>
Uhh I just wanted to merge the TS fixed from main here. And how did you
modify runtime.js? Does the script process the output of the paraglide
compilation result?
—
Reply to this email directly, view it on GitHub
<#366 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAXXDPIJN53PJKHTAHRXML3DWLOZAVCNFSM6AAAAAB7G2EXGCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSNZUGE3DOOJYGY>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
Collaborator
|
Okay yup found it, did you see the two review comments I left? |
Collaborator
Author
|
Ah. Yes. But guessed UX wrong and replied in my own review.
…On Sun, 15 Jun 2025, 20:50 Wituareard, ***@***.***> wrote:
*Wituareard* left a comment (PauseAI/pauseai-website#366)
<#366 (comment)>
Okay yup found it, did you see the two review comments I left?
—
Reply to this email directly, view it on GitHub
<#366 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAXXDMHZUEONZVGQJFV7N33DXE7JAVCNFSM6AAAAAB7G2EXGCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSNZUGY3DENJSGE>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
Collaborator
|
Hmm I don't see a separate review either. Maybe it hasn't been published or something like that? |
Collaborator
Author
|
… On Mon, 16 Jun 2025, 08:28 Wituareard, ***@***.***> wrote:
*Wituareard* left a comment (PauseAI/pauseai-website#366)
<#366 (comment)>
Hmm I don't see a separate review either. Maybe it hasn't been published
or something like that?
—
Reply to this email directly, view it on GitHub
<#366 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAXXDNNAIEJ6F33NDAUQCT3DZWX5AVCNFSM6AAAAAB7G2EXGCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSNZVGM4TSMJWGQ>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
Collaborator
|
The links don't lead anywhere for me. You might have started a review and not posted it yet |
Wituareard
approved these changes
Jun 19, 2025
Collaborator
|
@anthonybailey You can merge if you want |
anthonybailey
pushed a commit
that referenced
this pull request
Jun 19, 2025
- Add complete L10N.md developer guide covering all modes, CLI usage, and workflows - Update README.md with clear quick start and pnpm targets - Update template.env with new L10N_ variable names and CI defaults - Clarify l10n vs translation terminology throughout These changes were originally reviewed in #366
anthonybailey
pushed a commit
that referenced
this pull request
Jun 19, 2025
…ose mode - Remove illegal `return` statement at ES module top level that caused SyntaxError - Wrap main filtering logic in `else` block to prevent duplication when --verbose is used - Fixes CI/CD build failures when --verbose flag is present in command line arguments These changes were originally reviewed in #366 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
anthonybailey
pushed a commit
that referenced
this pull request
Jun 19, 2025
Prevents accidental writes to production l10n cage from local development while supporting CI/CD workflows. Implements dynamic branch detection with fallbacks: - L10N_BRANCH environment override - CI environment detection (Netlify PR previews, branch deploys) - Current git branch as fallback Key safety features: - Blocks local development writes to main cage branch - Tests git authentication upfront to prevent failed commits - SSH auto-detection and switching for easier Git operations - CI environments error rather than fall back to dry-run with e.g. invalid API keys - Automatic branch creation and upstream tracking - Comprehensive test coverage (114 test lines) See L10N.md "Branch Safety System" section for usage. A later commit will integrate the new feature. These changes were originally reviewed in #366
anthonybailey
pushed a commit
that referenced
this pull request
Jun 19, 2025
Creates the Mode class implementing the three l10n operating modes: - en-only: No l10ns bothered, maximum speed (default for local dev) - dry-run: Uses captured l10ns only, no LLM calls (missing API key or --dry-run flag) - perform: Prompts LLMs to capture new l10ns into cage (valid API key + proper branch) Key features: - Centralized mode determination replacing scattered logic - Dropped dry-run based on isDev in favor of explicit API key env choice - Safe defaults prevent expensive operations in development - Clear mode announcements via mode.announce() - Branch safety integration for perform mode validation - Comprehensive test coverage (295 test lines, 100% coverage) See L10N.md "L10n Modes" section for behavior details. A later commit will integrate this as yet unused new feature. These changes were originally reviewed in #366
anthonybailey
pushed a commit
that referenced
this pull request
Jun 19, 2025
Enables selective retranslation of specific files using familiar glob patterns.
Supports standard minimatch syntax including wildcards, character classes, and brace expansion.
Usage examples:
- `pnpm l10n --force "*.md"` - All markdown files
- `pnpm l10n --force "2024-*"` - Files with specific prefix
- `pnpm l10n --force "{join,donate}.md"` - Multiple specific files
- `pnpm l10n --force en.json proposal.md` - Mixed file types
Key features:
- Clean module extraction in force.ts with resolve() function
- Comprehensive help system with examples and syntax guide
- Integration tests against real filesystem (143 test lines)
- Proper CLI argument parsing (fixed minimist boolean handling)
See L10N.md "Force Mode Patterns" section for complete syntax guide.
This as yet unused new feature will be integrated in a later commit.
These changes were originally reviewed in #366
anthonybailey
pushed a commit
that referenced
this pull request
Jun 19, 2025
…hanges) Migrates from "translation" to "l10n" terminology with strategic commit splitting to preserve git file history. Renames core files and directory structure: Directory migration: - scripts/translation/ → scripts/l10n/ Key file renames: - translate.ts → run.ts (main entry point) - translate-core.ts → heart.ts (core l10n logic) - Keep git-ops.ts, prompts.ts, utils.ts, etc. Limited terminology updates in moved files to ensure git detects renames. Note: This intermediate state does not build - completed in next commit. Part of comprehensive terminology migration to "l10n cage" architecture. See L10N.md for the new terminology and concepts. These changes were originally reviewed in #366
anthonybailey
pushed a commit
that referenced
this pull request
Jun 19, 2025
…features As noted, this applies large changes to already moved git-ops, heart and run; also appropriately changes other files outside of scripts/l10n. Completes the transition from "translation" to "l10n cage" architecture with full integration of the new Mode, Branch Safety, and Force systems. Terminology migration: - Function names: translate() → l10nFromLLM(), translateOrLoad*() → retrieve*() - Parameter names: languageTag → locale, translationOptions → options - Type names: TranslationOptions → Options, TargetStrategy → Targeting - Comments and documentation: Complete "l10n cage" terminology throughout - Environment variables: Uses L10N_OPENROUTER_API_KEY, L10N_BRANCH Feature integration: - Mode system: Integrated in run.ts with mode.announce() and safe defaults - Branch safety: Integrated l10nCageBranch() and pushWithUpstream() - Force mode: Added resolveForcePatterns() and --force CLI support CLI simplification: - Removed redundant pnpm scripts (l10n:dry-run, l10n:estimate, etc.) - Unified to `pnpm l10n` with --dry-run, --force, --verbose flags - Updated dev/build integration for automatic l10n invocation Environment improvements: - isDev() now uses CI detection instead of NODE_ENV for consistent local defaults - Cache location: l10n-cage/ replaces src/temp/translations/ - Package: Added minimatch dependency for glob pattern support Also reintroduces "inlang:settings" target for "pnpm check" Action compatibility. See L10N.md for complete documentation of new architecture. These changes were originally reviewed in #366
Collaborator
Author
PR Successfully Merged via Reorganized CommitsThis PR has been merged to main through a series of carefully reorganized commits to maintain clean project history. What was done:
Merged commits:
All changes from this PR are now in main. The branch divergence was handled by rebasing on the latest main before merging. Thank you @Wituareard for the reviews! 🎉 |
Collaborator
Author
|
Closing as completed - all changes have been merged to main via the reorganized commits listed above. The deployment has completed successfully:
Thank you for the reviews and for this significant l10n infrastructure improvement! |
Collaborator
Author
|
(... I forced pushed the state from main onto our (deliberately ephemeral) First thing was that of course I'd renamed an environmental variable: it's For the moment I just supplied my own key for the variable in branch previews. We have further different keys under After the easy fix, I am seeing contention for Git operations in subsequent failed builds. Is entirely possible I've unserialized some previously serial read or commit or push operations in passing. The Git library we've been using is pretty crappy. Max processes seems the same as before. Should be able to dig in locally. ...) |
anthonybailey
commented
Jun 19, 2025
Collaborator
Author
Follow-up: Netlify CI Issues Resolved ✅After merging this PR, we discovered Netlify was caching broken l10n-cage directories between builds, causing authentication failures and build errors. This has now been comprehensively fixed in commit e18e90b on l10-preview: Key fixes:
Result: Netlify builds now complete successfully with proper error handling and no cache-related Git failures. The l10n infrastructure is now fully robust and ready for production use. 🎉 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR implements a large change to build and l10n infrastructure. Starting with comprehensive documentation, followed by the implementation commits that fulfill it.
📖 Documentation
View the new documentation directly: