Multilingual glossary, LLM translation, and reading-level support

.env.template

@@ -4,4 +4,14 @@ PUBLIC_FIREBASE_AUTH_DOMAIN = wordplay-dev.firebaseapp.com
 PUBLIC_FIREBASE_PROJECT_ID = demo-wordplay
 PUBLIC_FIREBASE_MESSAGING_SENDER_ID = 123456789123
 PUBLIC_FIREBASE_APP_ID = 1:123456789123:web:1234567890123456789012
-PUBLIC_FIREBASE_MEASUREMENT_ID = G-FAKEFAKEFA
+PUBLIC_FIREBASE_MEASUREMENT_ID = G-FAKEFAKEFA
+
+# Optional: Anthropic API key for the Claude translation backend used by the
+# offline locales CLI (npm run locales-translate). Get one at console.anthropic.com.
+# Without it, translation falls back to Google.
+#
+# Do NOT put it here or in .env — `npm run env` regenerates .env from
+# .env.<project> and would wipe it. Instead create a gitignored .env.local
+# (which the locales CLI also loads, and no script overwrites):
+#     ANTHROPIC_API_KEY = sk-ant-...
+# or export it in your shell.

.github/workflows/translate.yml

@@ -37,9 +37,11 @@ jobs:
             - run: npm run locales-fix
               name: Repair locale structure
 
-            # translate -> npm run locales-translate; override -> npm run override
-            - run: npm run ${{ inputs.mode == 'override' && 'override' || 'locales-translate' }}
+            # translate -> npm run locales-translate; override -> npm run locales-override
+            - run: npm run ${{ inputs.mode == 'override' && 'locales-override' || 'locales-translate' }}
               name: Generate machine translations
+              env:
+                  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 
             - name: Commit translations to the PR branch
               run: |

.gitignore

@@ -3,6 +3,7 @@ node_modules
 .DS_Store
 **/.DS_Store
 .env
+.env.local
 .env.wordplay-dev
 .env.wordplay-prod
 .env.demo

CHANGELOG.md

@@ -4,25 +4,29 @@ We'll note all notable changes in this file, including bug fixes, enhancements,
 Dates are in `YYYY-MM-DD` format and versions are in [semantic versioning](http://semver.org/) format.
 These notes are publicly posted in [production](https://wordplay.dev/updates), so we write them to an audience of teachers and youth.
 
-## 0.25.0 - 2026-06-22
+## 0.25.0 - 2026-06-27
 
 ### Added
 
 - 🌐 When you pick more than one language for Wordplay, we now show the interface in all of them at once. Your first language appears full size, and each other language follows it a little smaller and lighter — in labels, tooltips, the [Guide](https://wordplay.dev/guide), the tutorial, and even error messages.
-- 📕 Added the first sentence of project documentation to the project previews (#897).
-- 📐 We added a writing layout setting, so your program's output can read top to bottom (vertical) instead of left to right. It follows your language automatically, or you can pick one (#220).
+- 🌐 We added a writing layout setting, so your program's output can read top to bottom (vertical) instead of left to right. It follows your language automatically, or you can pick one (#220).
 - 📖 When you look at a concept in the [Guide](https://wordplay.dev/guide), we now show a link to the lesson that teaches it and a list of how-to's that use it, so it's easier to learn more (#769).
+- 📖 We added a glossary to the [Guide](https://wordplay.dev/guide) that explains the key words and ideas used across Wordplay. You can search it, or hover any term in the docs to see what it means (#780).
+- 📕 Added the first sentence of project documentation to the project previews (#897).
+- 📝 When you help translate Wordplay, we now point out text that may be hard to read and suggest when a key word should link to the glossary, so translations stay clear and easy to read (#460).
 
 ### Changed
 
 - 🌐 We made Wordplay work much better for right-to-left languages like Arabic and Hebrew. Menus, buttons, text, and the things your programs show on stage now flow from right to left to match how you read.
+- 🌐 We now use Claude to translate Wordplay into other languages. The wording is clearer, key words stay consistent, and the small example programs in the docs get translated too, not just the words around them.
+- 🌐 We made translating your own project into another language better: names, text, and documentation now translate together, with clearer wording.
 
 ### Fixed
 
 - 📕 We re-organized the how-to editing and viewing panels to offer much more width for viewing.
 - 🖱️ We fixed the code examples in the [Guide](https://wordplay.dev/guide) so you can drag pieces of them into your project.
 
-## 0.24.0 - 2026-06-18
+## 0.24.0 - 2026-06-20
 
 This abbreviated week we fleshed out the multilingual and text processing part of the programming language.
 

LANGUAGE.md

@@ -127,6 +127,10 @@ An external example embeds code from another programming language for documentat
 
 A concept link references a documented concept (e.g. `@Phrase`). A concept and one of its members (a property, function, or other subconcept) are separated by `.`, mirroring property access (e.g. `@Color.random`, `@Phrase.size`). A `/` separator instead references something that is not a concept: a UI element (`@UI/toolbar`), a how-to (`@How/...`), or a creator-defined character (`@username/charactername`). The separator must be followed by a name, so a sentence-ending period after a link (e.g. `see @Color.`) is left as punctuation.
 
+A bare lowercase `@term` (no separator) references a **glossary term** rather than a documented concept (e.g. `@value`, `@expression`). Resolution is by id: an `@id` resolves to a concept when the id is a concept's, otherwise to a glossary term — so concepts (capitalized ids like `@Phrase`) and glossary terms (lowercase ids) share the `@` reference syntax.
+
+A `$` mention substitutes a named template input (e.g. `$expected`), with `$?`/`$!` as special placeholders. `$` is only for input substitution; documented things — concepts and glossary terms alike — are referenced with `@` (above).
+
 > words → _any sequence of characters between `markup` that aren't markup delimeters above_
 
 Compound data structures have several delimiters:

functions/package.json

@@ -17,6 +17,7 @@
     },
     "main": "lib/index.js",
     "dependencies": {
+        "@anthropic-ai/sdk": "^0.106.0",
         "@google-cloud/translate": "^9",
         "@supercharge/promise-pool": "^3",
         "firebase-admin": "^13",