wuchale 0.1.0 → 0.1.1

package/README.md

@@ -35,7 +35,10 @@ minimal and constant-time.
 ### 🧩 Full Nesting Support
 
 Handles deeply nested markup and interpolations — mixed conditionals, loops,
-and awaits — by compiling them into nested Svelte snippets.
+and awaits — by compiling them into nested Svelte snippets. That means you can
+go as crazy as
+[this test](https://github.com/K1DV5/wuchale/blob/main/tests/complicated/app.svelte)
+and it will still extract the correct texts.
 
 ### 📦 No String Parsing at Runtime
 
@@ -56,8 +59,9 @@ optional integration with external tools.
 
 ### 🚀 Tiny Footprint
 
-Adds just 2 packages (your own) to `node_modules`, and only a few kilobytes to
-the bundle. No 90MB dependency trees like some existing solutions.
+Adds just 2 packages (itself and `pofile`) to `node_modules`, as the other
+dependency is Svelte itself. No 200 packages and 90MB dependency trees like
+some existing solutions.
 
 ### ✨ Ready for Svelte 5
 
@@ -79,11 +83,39 @@ Add to your Vite config:
 import { svelte } from '@sveltejs/vite-plugin-svelte'
 import { wuchale } from 'wuchale'
 
-export default { plugins: [ wuchale(), svelte(), ] }
+export default {
+    plugins: [
+        wuchale(),
+        svelte(),
+    ]
+    // ...your other config
+}
 
 ```
 
-Use in your Svelte files:
+Create `/locales/` if it doesn't exist, and then set it up in your main
+component. Assuming `/src/App.svelte`:
+
+```svelte
+<script>
+    import {setTranslations} from 'wuchale/runtime.svelte'
+
+    let locale = $state('en')
+
+    $effect.pre(() => {
+        import(`../locales/${locale}.json`).then(mod => {
+            setTranslations(mod.default)
+        })
+    })
+</script>
+```
+
+Note that you manage the state of which locale is active and how to download
+the compiled `.json`. This is to allow maximum flexibility, meaning you can use
+lazy loading (like this example) or you can import it directly and it will be
+bundled by Vite. After that, you notify `wuchale` to set it as the current one.
+
+Then finally you write your Svelte files naturally:
 
 ```svelte
 
@@ -98,6 +130,8 @@ import WuchaleTrans, { wuchaleTrans } from 'wuchale/runtime.svelte'
 <h1>{wuchaleTrans(0)}</h1> <!-- Extracted "Hello" as index 0 -->
 ```
 
+Full example below.
+
 ## 📦 How It Works
 
 ### Process
@@ -135,6 +169,8 @@ Input:
 
 ```svelte
 
+<p>Hi there!</p>
+
 <p>Hello <b>{userName}</b></p>
 
 ```
@@ -142,19 +178,62 @@ Input:
 Output:
 
 ```svelte
+<script>
+import WuchaleTrans, { wuchaleTrans } from 'wuchale/runtime.svelte'
+</script>
 
-<p>{wuchaleTrans(0, <b>{userName}</b>)}</p>
+<p>{wuchaleTrans(0)}</p>
+
+<p>
+  {#snippet wuchaleSnippet0(ctx)}
+      <b>{ctx[1]}</b>
+  {/snippet}
+  <WuchaleTrans tags={[wuchaleSnippet0]} id={1} args={[userName]} />
+</p>
 
 ```
 
-Catalog (PO):
+Extracted catalog (PO) for `en`:
 
 ```nginx
 
-msgid "Hello {0}" msgstr "Bonjour {0}"
+msgid "Hi there!"
+msgstr "Hi there!"
+
+msgid "Hello {0}"
+msgstr "Hello {0}"
 
 ```
 
+Extracted catalog (PO) for `es`, initially empty `msgstr`, but after a translator or Gemini translates it:
+
+```nginx
+
+msgid "Hi there!"
+msgstr "¡Hola!"
+
+msgid "Hello {0}"
+msgstr "Hola {0}"
+
+```
+
+Which is then automatically compiled to:
+
+```json
+[
+    "¡Hola!",
+    [
+        "Hola ",
+        [
+            0,
+            0
+        ]
+    ]
+]
+```
+
+This is what you import when you set it up above in `App.svelte`.
+
 ## Supported syntax
 
 Text can be in three places: markup, script and attributes. Script means not
@@ -196,6 +275,35 @@ necessary to have a separate plurals support because you can do something like:
 And they will be extracted separately. You can also make a reusable function
 yourself.
 
+## Configuration
+
+To configure `wuchale`, you pass an object that looks like the following (the
+default) to `wuchale()` in your `vite.config.js` `vite.config.ts`:
+
+```javascript
+export const defaultOptions = {
+    sourceLocale: 'en',
+    otherLocales: ['am'],
+    localesDir: './locales',
+    importFrom: 'wuchale/runtime.svelte',
+    heuristic: defaultHeuristic,
+    geminiAPIKey: 'env',
+}
+```
+
+While the others are self explanatory, the `heuristic` is a function that
+decides what text to extract and what not to. The `defaultHeuristic` is the
+implementation of the above rules, but you can roll your own and provide it
+here. The function should receive the following arguments:
+
+- `text`: The candidate text
+- `scope`: Where the text is located, i.e. it can be one of `markup`, `script`, and `attribute`
+
+And it should return an object with two properties:
+
+- `extract` (boolean): Whether to extract it or not
+- `replace` (`string`): The string to replace it with. This is how you specify how to remove parts such as the prefixes above (`+` and `-`).
+
 ## 🧹 Cleaning
 
 Unused keys are marked as obsolete during a production build. Obsoletes are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wuchale",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "i18n for svelte without turning your codebase upside down",
   "main": "index.js",
   "scripts": {