@inlang/paraglide-js 1.3.2 → 1.3.3

package/README.md

@@ -4,7 +4,7 @@
 
 # Simple, adaptable, and tiny i18n library for JS
 
-Get started instantly with the following command:
+Get started with:
 
 ```bash
 npx @inlang/paraglide-js@latest init
@@ -29,7 +29,7 @@ Treeshaking gives us superpowers. With it, each page of your app only loads the
 
 ### 1. Initialize paraglide-js
 
-You can initialize paraglide-js by running the following command in your terminal:
+Initialize paraglide-js whith:
 
 ```bash
 npx @inlang/paraglide-js@latest init
@@ -37,13 +37,13 @@ npx @inlang/paraglide-js@latest init
 
 This will:
 
-1. Install the necessary dependencies
-2. Call the Paraglide compiler in your `build` script
-3. Set up any necessary configuration files
+1. Install necessary dependencies
+2. Add the Paraglide compiler to your `build` script
+3. Set up configuration files
 
 ### 2. Set up an adapter (optional)
 
-Adapters are framework specific integrations for Paraglide. If you are using a framework, using an adapter is recommended (but not required). If you don't use a framework, you can skip this step.
+Adapters are framework-integrations for Paraglide. If you are using a framework, using an adapter is recommended , but not required.
 
 <doc-links>
 	<doc-link title="Adapter for NextJS" icon="tabler:brand-nextjs" href="https://inlang.com/m/osslbuzt/library-inlang-paraglideJsAdapterNextJs" description="Go to Library"></doc-link>
@@ -57,36 +57,34 @@ Adapters are framework specific integrations for Paraglide. If you are using a f
 # Usage
 
 Running your `build` script will generate a `src/paraglide` folder. This folder contains all the code that you need to use paraglide-js.
-Throughout this guide, you will see imports from `./paraglide/*`. These are all to this folder.
 
-> Tip: If you are using a bundler, you can set up an alias to `./src/paraglide` to make the imports shorter. We recommend `$paraglide/*`
+> Tip: If you are using a bundler, you can set up an alias to `./src/paraglide` to make the imports shorter.
+
+## Adding Messages
+
+By default, paraglide expects your messages to be in `messages/{lang}.json`. 
+```json
+{
+	"hello": "Hello world!"
+	"loginHeader": "Hello {name}, please login to continue."
+}
+```
 
 ## Using Messages
 
-The compiled messages are placed in `./paraglide/messages.js`. You can import them all with `import * as m from "./paraglide/messages"`. Don't worry, your bundler will only bundle the messages that you actually use.
+You can import messages with `import * as m from "./paraglide/messages"`. Don't worry, your bundler will only include the messages that you actually use.
 
 ```js
-// m is a namespace that contains all messages of your project
-// a bundler like rollup or webpack only bundles
-// the messages that are used
 import * as m from "./paraglide/messages.js"
 import { setLanguageTag } from "./paraglide/runtime.js"
 
-// use a message
 m.hello() // Hello world!
-
-// message with parameters
 m.loginHeader({ name: "Samuel" }) // Hello Samuel, please login to continue.
-
-// change the language
-setLanguageTag("de")
-
-m.loginHeader({ name: "Samuel" }) // Hallo Samuel, bitte melde dich an, um fortzufahren.
 ```
 
-If you want to dynamically choose between a set of messages, you can create a record of messages and index into it. Note that this will not be tree-shaken by your bundler.
+If you want to choose between messages at runtime, you can create a record of messages and index into it.
 
-```js
+```ts
 import * as m from "./paraglide/messages.js"
 
 const season = {
@@ -94,26 +92,34 @@ const season = {
 	summer: m.summer,
 	autumn: m.autumn,
 	winter: m.winter,
-}
+} as const;
 
 const msg = season["spring"]() // Hello spring!
 ```
 
-Paraglide JS provides several exports from `./paraglide/runtime.js`:
 
-| Variable                    | Description                                                           |
-| --------------------------- | --------------------------------------------------------------------- |
-| `sourceLanguageTag`         | The source language tag of the project                                |
-| `availableLanguageTags`     | All language tags of the current project                              |
-| `type AvailableLanguageTag` | An Type representing a valid language tag                             |
-| `languageTag()`             | Returns the language tag of the current user                          |
-| `setLanguageTag()`          | Sets the language tag of the current user                             |
-| `onSetLanguageTag()`        | Registers a listener that is called whenever the language tag changes |
-| `isAvailableLanguageTag()`  |  Checks if a value is a valid language tag                            |
+### (optional) Using the [Sherlock](https://inlang.com/m/r7kp499g/app-inlang-ideExtension) IDE Extension
+
+[Sherlock](https://inlang.com/m/r7kp499g/app-inlang-ideExtension) integrates with paraglide to give you the optimal dev-experience. 
+
+![VsCode screenshot showing Sherlock adding inlay hints next to messages and making an "extract message" code action available for hardcoded text](https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/sherlock-preview.png)
+
+## Adding Languages
+
+You can declare which languages you support in `./project.inlang/settings.json` in the `languageTags` array.
+
+```json
+// project.inlang/settings.json
+{
+	"languageTags": ["en", "de"]
+}
+```
+
+Then create another `messages/{lang}.json` file and get translating!
 
 ## Setting the language
 
-You can set the current [language tag](https://www.inlang.com/m/8y8sxj09/library-inlang-languageTag) by calling `setLanguageTag()`. Any subsequent calls to either `languageTag()` or a message function will return the new language tag.
+You can set the [language tag](https://www.inlang.com/m/8y8sxj09/library-inlang-languageTag) by calling `setLanguageTag()`. Any subsequent calls to either `languageTag()` or a message function will use the new language tag.
 
 ```js
 import { setLanguageTag } from "./paraglide/runtime.js"
@@ -126,22 +132,15 @@ setLanguageTag("en")
 m.hello() // Hello world!
 ```
 
-The [language tag](https://www.inlang.com/m/8y8sxj09/library-inlang-languageTag) is global, so you need to be careful with it on the server to make sure multiple requests don't interfere with each other. That's why we recommend using an adapter for your framework. Adapters integrate with the framework's lifecycle and ensure that the language tag is managed correctly.
-
-## Adding Languages
+The [language tag](https://www.inlang.com/m/8y8sxj09/library-inlang-languageTag) is global, so you need to be careful with it on the server to make sure multiple requests don't interfere with each other.
 
-You can define which languages you want to support in `./project.inlang/settings.json`. Just edit the `languageTags` array.
+You will need to call `setLanguageTag` on both the server and the client, since they run in separate processes.
 
-```json
-// project.inlang/settings.json
-{
-	"languageTags": ["en", "de"]
-}
-```
+## Reacting to language changes
 
-## Reacting to a language change
+Messages aren't reactive, so you will need to trigger a re-render when the language changes. You can register a callback using `onSetLanguageTag()`. It is called whenever the [language tag](https://www.inlang.com/m/8y8sxj09/library-inlang-languageTag) changes.
 
-You can react to a language change by registering a callback using `onSetLanguageTag()`. This function is called whenever the [language tag](https://www.inlang.com/m/8y8sxj09/library-inlang-languageTag) changes.
+If you are using an adapter this is likely done for you.
 
 ```js
 import { setLanguageTag, onSetLanguageTag } from "./paraglide/runtime.js"
@@ -158,36 +157,52 @@ setLanguageTag("en") // The language changed to en
 There are a few things to know about `onSetLanguageTag()`:
 
 - You can only register one listener. If you register a second listener it will throw an error.
-- It shouldn't be used on the server.
+- `setLanguageTag` shouldn't be used on the server.
+
+## Getting a message in a specific language
 
-The main use case for `onSetLanguageTag()` is to trigger a rerender of your app's UI when the language changes. Again, if you are using an adapter this is handled for you.
+You can import a message in a specific language from `paraglide/messages/{lang}.js`. This is great if you always need the same language in a given file. 
 
-## Forcing a language
+```ts
+import * as m from "./paraglide/messages/de.js"
+m.hello() // Hallo Welt
+```
 
-It's common that you need to force a message to be in a certain language, especially on the server and during tests. You can do this by passing an options object to the message function as a
-second parameter.
+If you want to force a language, but don't know ahead of time _which_ language you can pass the `languageTag` option as the second parameter to a message function. This is often needed on the server.
 
 ```js
 import * as m from "./paraglide/messages.js"
 const msg = m.hello({ name: "Samuel" }, { languageTag: "de" }) // Hallo Samuel!
 ```
 
+## Lazy-Loading
+
+Paraglide consciously discourages lazy-loading translations since it seriously hurts
+your web-vitals. Learn more about why lazy-loading is bad & what to do instead in [this blog post](https://inlang.com/g/mqlyfa7l/guide-lorissigrist-dontlazyload).
+
+If you _really_ want to do it anway, you can lazily import the language-specific message files. Be careful with this, as it's easy to accidenally break tree-shaking.
+
+```ts
+const lazyGerman = await import("./paraglide/messages/de.js")
+```
+
 ## Usage with a Bundler
 
 We provide bundler plugins to make it easier to use Paraglide with a bundler. If you
-are using one of these bundlers, we recommed using the corresponding plugin.
+are using one we recommed using the corresponding plugin.
 
 - [Rollup](https://github.com/opral/monorepo/tree/main/inlang/source-code/paraglide/paraglide-js-adapter-rollup)
 - [Webpack](https://github.com/opral/monorepo/tree/main/inlang/source-code/paraglide/paraglide-js-adapter-webpack)
 - [Vite](https://github.com/opral/monorepo/tree/main/inlang/source-code/paraglide/paraglide-js-adapter-vite)
 
-These plugins make sure to rerun the `compile` script whenever you build your project. That way you don't need to modify your build script in `package.json`. If you are using a bundler with a dev-server, like Vite, the plugins also make sure to rerun the `compile` script whenever your messages change.
+These plugins make sure to compile your messages whenever you build your project. If your bundler has a dev-server, like Vite, the plugin also makes sure to recompile whenever your messages change.
 
 # Playground
 
 You can find many examples for how to use paraglide on codesandbox, or in [our GitHub repository](https://github.com/opral/monorepo/tree/main/inlang/source-code/paraglide).
 
 <doc-links>
+    <doc-link title="NextJS + Paraglide JS" icon="lucide:codesandbox" href="https://stackblitz.com/~/LorisSigrist/paraglide-next-app-router-example" description="Play around with NextJS and Paraglide JS"></doc-link>
     <doc-link title="Svelte + Paraglide JS" icon="lucide:codesandbox" href="https://stackblitz.com/~/github.com/LorisSigrist/paraglide-sveltekit-example" description="Play around with Svelte and Paraglide JS"></doc-link>
     <doc-link title="Astro + Paraglide JS" icon="lucide:codesandbox" href="https://stackblitz.com/~/github.com/LorisSigrist/paraglide-astro-example" description="Play around with Astro and Paraglide JS"></doc-link>
 </doc-links>
@@ -207,7 +222,7 @@ Inlang Paraglide-JS consists of four main parts:
 | **Compiler** | Compiles messages into tree-shakable message functions                                                                       |
 | **Messages** | The compiled tree-shakable message functions                                                                                 |
 | **Runtime**  | A runtime that resolves the [language tag](https://www.inlang.com/m/8y8sxj09/library-inlang-languageTag) of the current user |
-| **Adapter**  | (optional) An adapter that adjusts the runtime for different frameworks                                                   |
+| **Adapter**  | (optional) An adapter that adjusts the runtime for different frameworks                                                      |
 
 ## Compiler
 
@@ -283,14 +298,12 @@ console.log(hello({ name: "Samuel" }))
 
 # Writing an Adapter
 
-Paraglide can be adapted to any framework or environment by calling `setLanguageTag()` and `onSetLanguageTag()`.
+An "adapter" is a library that integrates with a framework's liefcycle and does two main things:
 
-The following example adapts Paraglide-JS to a fictitious metaframework like NextJS, SolidStart, SvelteKit, or Nuxt.
+- Calls `setLanguageTag()` at appropriate times to set the language
+- Reacts to `onSetLanguageTag()`, usually by navigating or relading the page.
 
-The goal is to provide a high-level understanding of how to adapt Paraglide to a framework. Besides this example, we recommend viewing the source-code of available adapters. In general, only two functions need to be called to adapt Paraglide to a framework:
-
-1.  `setLanguageTag()` can be used to set a getter function for the [language tag](https://www.inlang.com/m/8y8sxj09/library-inlang-languageTag). The getter function can be used to resolve server-side language tags or to resolve the language tag from a global state management library like Redux or Vuex.
-2.  `onSetLanguageTag()` can be used to trigger side-effects such as updating the UI, or requesting the site in the new language from the server.
+Here is an example that adapts Paraglide-JS to a fictitious metaframework like NextJS or SvelteKit.
 
 ```tsx
 import { setLanguageTag, onSetLanguageTag } from "../paraglide/runtime.js"
@@ -324,7 +337,7 @@ else {
 	})
 }
 
-// render the app
+// make sure the app renders _after_ you've done your setup
 render((page) => (
 	<html lang={request.languageTag}>
 		<body>{page}</body>
@@ -334,8 +347,9 @@ render((page) => (
 
 # Community
 
-We are grateful for all the support we get from the community. Here are just a few of the comments we've received over the last few weeks.
-Of course we are open to and value criticism as well. If you have any feedback, please let us know directly on [GitHub](https://github.com/opral/monorepo/discussions/1464)
+We are grateful for all the support we get from the community. Here are a few comments we've received recently. 
+
+If you have any feedback / problems, please let us know on [GitHub](https://github.com/opral/inlang-paraglide-js/issues/new)
 
 <doc-comments>
 <doc-comment text="Just tried Paraglide JS from @inlangHQ. This is how i18n should be done! Totally new level of DX for both implementation and managing translations! Superb support for SvelteKit as well ⭐" author="Patrik Engborg" icon="mdi:twitter" data-source="https://twitter.com/patrikengborg/status/1747260930873053674"></doc-comment>
@@ -347,7 +361,7 @@ Of course we are open to and value criticism as well. If you have any feedback,
 
 # Roadmap
 
-Of course, we're not done yet! We plan on adding the following features to Paraglide JS in the upcoming weeks:
+Of course, we're not done yet! We plan on adding the following features to Paraglide JS soon:
 
 - [ ] Pluralization ([Join the Discussion](https://github.com/opral/monorepo/discussions/2025))
 - [ ] Formatting of numbers and dates ([Join the Discussion](https://github.com/opral/monorepo/discussions/992))
@@ -367,6 +381,6 @@ Paraglide JS is part of the inlang ecosystem, so it integrates nicely with all t
 - [Fink](https://inlang.com/m/tdozzpar/app-inlang-finkLocalizationEditor) - An Online UI for editing translations. Changes made in Fink are committed to a translation branch or submitted via pull request.
 - [Parrot](https://inlang.com/m/gkrpgoir/app-parrot-figmaPlugin) - A Figma Plugin for previewing translations right in your Figma designs. This avoids any layout issues that might occur due to different text lengths in different languages.
 
-# Pricing 
+# Pricing
 
 <doc-pricing></doc-pricing>

package/dist/index.js

@@ -35660,8 +35660,11 @@ function reexportAliases(message) {
  * @see inlang.com/link.
  * ---
  * @deprecated reference the message by id \`m.${message.id}()\` instead
+ * 
+ * @param {Parameters<typeof ${message.id}>} args
+ * @returns {ReturnType<typeof ${message.id}>}
  */
-export const ${message.alias["default"]} = ${message.id};
+export const ${message.alias["default"]} = (...args) => ${message.id}(...args);
 `;
   }
   return code;
@@ -40054,8 +40057,9 @@ async function pathExists2(filePath, nodeishFs) {
 }
 
 // ../../cross-sell/cross-sell-sherlock/dist/recommendation/recommendation.js
+var vsCodePath = "./.vscode";
 async function addRecommendationToWorkspace(fs3, workingDirectory) {
-  const vscodeFolderPath = normalizePath(joinPath(workingDirectory ?? "", "./.vscode"));
+  const vscodeFolderPath = workingDirectory ? normalizePath(joinPath(workingDirectory ?? "", vsCodePath)) : vsCodePath;
   const extensionsJsonPath = joinPath(vscodeFolderPath, "extensions.json");
   if (!await pathExists2(vscodeFolderPath, fs3)) {
     await fs3.mkdir(vscodeFolderPath);
@@ -40081,7 +40085,7 @@ async function addRecommendationToWorkspace(fs3, workingDirectory) {
   }
 }
 async function isInWorkspaceRecommendation(fs3, workingDirectory) {
-  const vscodeFolderPath = normalizePath(joinPath(workingDirectory ?? "", "./.vscode"));
+  const vscodeFolderPath = workingDirectory ? normalizePath(joinPath(workingDirectory ?? "", vsCodePath)) : vsCodePath;
   const extensionsJsonPath = joinPath(vscodeFolderPath, "extensions.json");
   if (!await pathExists2(extensionsJsonPath, fs3) || !await pathExists2(vscodeFolderPath, fs3)) {
     return false;
@@ -40094,11 +40098,11 @@ async function isInWorkspaceRecommendation(fs3, workingDirectory) {
 }
 
 // ../../cross-sell/cross-sell-sherlock/dist/index.js
-async function isAdopted(fs3, workingDirectory) {
-  return isInWorkspaceRecommendation(fs3, workingDirectory);
+async function isAdopted(args) {
+  return isInWorkspaceRecommendation(args.fs, args.workingDirectory);
 }
-async function add2(fs3, workingDirectory) {
-  await addRecommendationToWorkspace(fs3, workingDirectory);
+async function add2(args) {
+  await addRecommendationToWorkspace(args.fs, args.workingDirectory);
 }
 
 // src/cli/commands/init.ts
@@ -40199,8 +40203,8 @@ var maybeAddVsCodeExtension = async (args, ctx) => {
     project.setSettings(settings);
   }
   try {
-    if (!await isAdopted(ctx.repo.nodeishFs)) {
-      await add2(ctx.repo.nodeishFs);
+    if (!await isAdopted({ fs: ctx.repo.nodeishFs })) {
+      await add2({ fs: ctx.repo.nodeishFs });
       ctx.logger.success(
         "Added the inlang Visual Studio Code extension (Sherlock) to the workspace recommendations."
       );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@inlang/paraglide-js",
   "type": "module",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"
@@ -64,12 +64,12 @@
     "typescript": "5.2.2",
     "vitest": "0.34.3",
     "@inlang/env-variables": "0.2.0",
-    "@inlang/cross-sell-sherlock": "0.0.2",
+    "@inlang/cross-sell-sherlock": "0.0.3",
     "@inlang/language-tag": "1.5.1",
     "@inlang/telemetry": "0.3.14",
+    "@inlang/sdk": "0.27.0",
     "@lix-js/client": "0.9.0",
     "@lix-js/fs": "0.6.0",
-    "@inlang/sdk": "0.27.0",
     "@inlang/plugin-message-format": "2.1.1"
   },
   "exports": {