@inlang/paraglide-js 1.0.0-prerelease.0

package/README.md

@@ -0,0 +1,239 @@
+# @inlang/paraglide-js
+
+## ATTENTION: Paraglide is in pre-release mode. Discuss the API at https://github.com/inlang/monorepo/discussions/1464
+
+<doc-gallery>TODO: adapter gallery</doc-gallery>
+
+- [x] the smallest, fastest, and most typesafe i18n library
+- [x] only bundles the messages that are used (tree-shaking)
+- [x] storage agnostic (JSON, YAML, CSV, etc.) 
+- [x] plug & play with the [inlang ecosystem](https://inlang.com/marketplace)
+
+# Usage
+
+Messages are imported as a namespace and can be used as follows:
+
+```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 "@inlang/paraglide-js/messages"
+import { setLanguageTag } from "@inlang/paraglide-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.
+
+```
+
+Paraglide JS exports four runtime variables and functions via "@inlang/paraglide-js":
+
+- `sourceLanguageTag`: the source language tag of the project
+- `languageTags`: all language tags of the current project
+- `languageTag()`: returns the language tag of the current user
+- `setLanguageTag()`: sets the language tag of the current user
+
+
+# Getting started
+
+## Available Adapters
+
+- TODO: add adapters 
+
+## Standalone
+
+1. Add paraglide as a dependency:
+
+```bash
+npm install @inlang/paraglide-js
+```
+
+2. Add the compiler to your build script:
+
+```diff
+{
+  "scripts": {
++    "build": "paraglide-js compile --namespace <your project name>"
+  }
+}
+```
+
+
+# Architecture 
+
+Inlang Paraglide JS leverages a compiler to emit a use-case optimized i18n library. 
+
+By leveraging a compiler, inlang Paraglide JS eliminates a class of edge cases while also being simpler, faster, and more reliable than other i18n libraries. The compiled runtime contains less than 50 LOC (lines of code) and is less than 1kb gzipped.
+
+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 of the current user
+- `ADAPTER`: (if required) an adapter that adjust the runtime for different frameworks
+
+<img src="./assets/architecture.svg">
+
+
+## COMPILER
+
+The compiler loads an inlang project and compiles the messages into tree-shakable and type safe message functions.
+
+### Example
+
+#### Input
+
+```js
+// messages/en.json
+
+hello: "Hello {name}!"
+
+loginButton: "Login"
+```
+
+#### Output
+
+```js
+// @inlang/paraglide-js/messages
+
+/**
+ * @param {object} params
+ * @param {string} params.name
+ */
+function hello({ name }) {
+  return `Hello ${name}!`
+}
+
+function loginButton() {
+  return "Login"
+}
+```
+
+
+## MESSAGES
+
+The compiled messages are importable as a namespace import (`import * as m`). 
+
+The namespace import ensures that bundlers like Rollup, Webpack, or Turbopack can tree-shake the messages that are not used.
+
+### Example
+
+Three compiled message functions exists in an examplary project.
+
+```js
+// @inlang/paraglide-js/<namespace>/messages
+
+
+export function hello(params) {
+  return `Hello ${params.name}!`
+}
+
+export function loginButton() {
+  return "Login"
+}
+
+export function loginHeader(params) {
+  return `Hello ${params.name}, please login to continue.`
+}
+```
+
+
+Only the message `hello` is used in the source code.
+
+```js
+// source/index.js
+
+import * as m from "@inlang/paraglide-js/<namespace>/messages"
+
+console.log(m.hello({ name: "Samuel" }))
+```
+
+The bundler tree-shakes (removes) `loginButton` and `loginHeader` and only includes `hello` in the output.
+
+```js
+// output/index.js
+
+function hello(params) {
+  return `Hello ${params.name}!`
+}
+
+console.log(hello({ name: "Samuel"}))
+```
+
+
+## RUNTIME
+
+View the source of your imports from `@inlang/paraglide-js/<namespace>` to find the latest runtime API and documentation. 
+
+## ADAPTER 
+
+
+
+Paraglide-JS can be adapted to any framework or environment by calling `setLanguageTag()` and `onSetLanguageTag()`. 
+
+1.  `setLanguageTag()` can be used to set a getter function for the language tag. 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 request the site in the new language from the server.
+
+
+### Writing an Adapter
+
+The following example adapts Paraglide-JS to a fictious metaframework like NextJS, SolidStart, SvelteKit, or Nuxt. 
+
+The goal is to provide a high-level understanding of how to adapt Paraglide-JS to a framework. Besides this example, we recommend to view the source-code of available adapters. In general, only two functions need to be called to adapt Paraglide-JS to a framework:
+
+1. `setLanguageTag()`: to set the language tag
+2. `onSetLanguageTag()`: to trigger a side-effect when the language changes
+
+
+
+
+```tsx
+import { setLanguageTag, onSetLanguageTag } from "@inlang/paraglide-js/<namespace>"
+import { isServer, request, render } from "@example/framework"
+
+
+// On a server, the language tag needs to be resolved on a 
+// per-request basis. Hence, we need to pass a getter 
+// function () => string to setLanguageTag.
+// 
+// Most frameworks offer a way to access the current
+// request. In this example, we assume that the language tag
+// is available in the request object.
+if (isServer){
+  setLanguageTag(() => request.languageTag)
+} 
+// On a client, the language tag could be resolved from 
+// the document's html lang tag.
+//
+// In addition, we also want to trigger a side-effect
+// to request the site if the language changes.
+else {
+  setLanguageTag(() => document.documentElement.lang)
+  
+  //! Make sure to call `onSetLanguageTag` after
+  //! the initial language tag has been set to
+  //! avoid an infinite loop. 
+
+  // route to the page in the new language
+  onSetLanguageTag((newLanguageTag) => {
+     window.location.pathname = `/${newLanguageTag}${window.location.pathname}`
+  })
+}
+
+// render the app
+render((page) => 
+  <html lang={request.languageTag}>
+    <body>
+      {page}
+    </body>
+  </html>
+)
+```
+

package/bin/run.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { cli } from "../dist/cli/main.js"
+
+cli.parse()

package/dist/cli/commands/compile.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare const compileCommand: Command;
+//# sourceMappingURL=compile.d.ts.map

package/dist/cli/commands/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/compile.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAInC,eAAO,MAAM,cAAc,SAsBxB,CAAA"}

package/dist/cli/commands/compile.js

@@ -0,0 +1,57 @@
+import { loadProject } from "@inlang/sdk";
+import consola from "consola";
+import { compile } from "../../compiler/compile.js";
+import fs from "node:fs/promises";
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { paraglideDirectory } from "../main.js";
+import dedent from "dedent";
+export const compileCommand = new Command()
+    .name("compile")
+    .summary("Compiles an inlang project into an importable library.")
+    .requiredOption("--project <path>", "The path to the project settings file.", "./project.inlang.json")
+    .requiredOption("--namespace <name>", dedent `
+		The import namespace of the compiled library. 
+		\nExample: --namespace frontend
+		-> import * as m from "@inlang/paraglide-js/frontend/messages"
+		\n`)
+    .action((options) => {
+    runCompileCommand({
+        projectPath: options.project,
+        namespace: options.namespace,
+        paraglideDirectory,
+    });
+});
+const runCompileCommand = async (args) => {
+    consola.info(`Compiling inlang project at "${args.projectPath}".`);
+    const project = exitIfErrors(await loadProject({ settingsFilePath: resolve(process.cwd(), args.projectPath), nodeishFs: fs }));
+    const output = compile({
+        messages: project.query.messages.getAll(),
+        settings: project.settings(),
+    });
+    const outputDirectory = `${args.paraglideDirectory}/dist/compiled-output` + (args.namespace ? `/${args.namespace}` : "");
+    for (const [fileName, fileContent] of Object.entries(output)) {
+        // create the compiled-output directory if it doesn't exist
+        await fs.access(outputDirectory).catch(async () => {
+            await fs.mkdir(outputDirectory, { recursive: true });
+        });
+        await fs.writeFile(`${outputDirectory}/${fileName}`, fileContent, {
+            encoding: "utf-8",
+        });
+    }
+    consola.success("Successfully compiled the project.");
+};
+/**
+ * Utility function to exit when the project has errors.
+ */
+const exitIfErrors = (project) => {
+    if (project.errors().length > 0) {
+        // two console statements for better output formatting
+        // because project.errors() internal .toString() method
+        // is better than manual processing.
+        consola.error(`The project has errors:`);
+        consola.log(project.errors());
+        process.exit(1);
+    }
+    return project;
+};

package/dist/cli/main.d.ts

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+/**
+ * The absolute path to the paraglide directory.
+ *
+ * slices a path
+ * from '/Users/samuel/example/repository/node_modules/paraglide-js/dist/cli/main.js'
+ * to   '/Users/samuel/example/repository/node_modules/paraglide-js'
+ */
+export declare const paraglideDirectory: string;
+export declare const cli: Command;
+//# sourceMappingURL=main.d.ts.map

package/dist/cli/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAUnC;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAA4D,CAAA;AAE7F,eAAO,MAAM,GAAG,SAqBb,CAAA"}

package/dist/cli/main.js

@@ -0,0 +1,40 @@
+import consola from "consola";
+import dedent from "dedent";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { compileCommand } from "./commands/compile.js";
+/**
+ * The path this file is executed from.
+ *
+ * Usually something like '/Users/samuel/example/repository/node_modules/paraglide-js/dist/cli/main.js'
+ */
+const metaUrlPath = fileURLToPath(import.meta.url);
+/**
+ * The absolute path to the paraglide directory.
+ *
+ * slices a path
+ * from '/Users/samuel/example/repository/node_modules/paraglide-js/dist/cli/main.js'
+ * to   '/Users/samuel/example/repository/node_modules/paraglide-js'
+ */
+export const paraglideDirectory = metaUrlPath.slice(0, metaUrlPath.indexOf("/dist/"));
+export const cli = new Command()
+    .name("paraglide-js")
+    .addCommand(compileCommand)
+    .hook("preAction", () => {
+    // ------------------- VALIDATE IF RUNNING FROM CORRECT FOLDER -------------------
+    // the CLI expects to be running from the dist folder of the specific paraglide package
+    // to compile the output in the correct directory
+    if (metaUrlPath.includes(`paraglide-js/dist/`) === false) {
+        consola.error(dedent `
+			The CLI is not running from the dist folder. 
+
+			This is likely an internal bug. Please file an issue at https://github.com/inlang/monorepo/issues.
+
+			Debug information: 
+
+			- metaUrlPath: ${metaUrlPath}
+			`);
+        process.exit(1);
+    }
+});
+cli.showHelpAfterError(true);

package/dist/compiled-output/example-javascript/messages.d.ts

@@ -0,0 +1,7 @@
+export function currentLanguageTag(params: {
+    languageTag: NonNullable<unknown>;
+}): string;
+export function greeting(params: {
+    name: NonNullable<unknown>;
+    count: NonNullable<unknown>;
+}): string;

package/dist/compiled-output/example-javascript/messages.js

@@ -0,0 +1,42 @@
+
+import { languageTag } from "./runtime.js"
+
+
+/**
+ * This message has been compiled by [inlang paraglide](https://inlang.com/marketplace/library.inlang.paraglideJs).
+ *
+ * - Don't edit the message manually. Use the [inlang ide extension](https://inlang.com/marketplace/app.inlang.ideExtension)
+ *   or the [web editor](https://inlang.com/marketplace/app.inlang.editor) to edit the message.
+ * 
+ * - The params are NonNullable<unknown> because inlang can't know the value type of a param (yet).
+ * 
+ * @param {{ languageTag: NonNullable<unknown> }} params
+ * @returns {string}
+ */
+  export const currentLanguageTag = (params) => {
+    const variants = {
+      "en": `The current language tag is "${params.languageTag}".`,
+  "de": `Der aktuelle Sprachtag ist "${params.languageTag}".`
+	}
+	return variants[languageTag()] ?? "currentLanguageTag"
+}
+
+
+/**
+ * This message has been compiled by [inlang paraglide](https://inlang.com/marketplace/library.inlang.paraglideJs).
+ *
+ * - Don't edit the message manually. Use the [inlang ide extension](https://inlang.com/marketplace/app.inlang.ideExtension)
+ *   or the [web editor](https://inlang.com/marketplace/app.inlang.editor) to edit the message.
+ * 
+ * - The params are NonNullable<unknown> because inlang can't know the value type of a param (yet).
+ * 
+ * @param {{ name: NonNullable<unknown>, count: NonNullable<unknown> }} params
+ * @returns {string}
+ */
+  export const greeting = (params) => {
+    const variants = {
+      "en": `Welcome ${params.name}! You have ${params.count} messages.`,
+  "de": `Hallo ${params.name}! Du hast ${params.count} Nachrichten.`
+	}
+	return variants[languageTag()] ?? "greeting"
+}

package/dist/compiled-output/example-javascript/runtime.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The project's source language tag.
+ *
+ * @example
+ *   if (newlySelectedLanguageTag === sourceLanguageTag){
+ *     // do nothing as the source language tag is the default language
+ *     return
+ *   }
+ */
+export const sourceLanguageTag: "en";
+/**
+ * The project's available language tags.
+ *
+ * @example
+ *   if (availableLanguageTags.includes(userSelectedLanguageTag) === false){
+ *     throw new Error("Language tag not available")
+ *   }
+ */
+export const availableLanguageTags: readonly ["en", "de"];
+/**
+ * Get the current language tag.
+ *
+ * @example
+ *   if (languageTag() === "de"){
+ *     console.log("Germany 🇩🇪")
+ *   } else if (languageTag() === "nl"){
+ *     console.log("Netherlands 🇳🇱")
+ *   }
+ *
+ * @type {() => AvailableLanguageTag}
+ */
+export let languageTag: () => AvailableLanguageTag;
+export function setLanguageTag(tag: AvailableLanguageTag | (() => AvailableLanguageTag)): void;
+export function onSetLanguageTag(fn: (languageTag: any) => void): void;
+/**
+ * A language tag that is available in the project.
+ */
+export type AvailableLanguageTag = (typeof availableLanguageTags)[number];

package/dist/compiled-output/example-javascript/runtime.js

@@ -0,0 +1,112 @@
+
+/** @type {((tag: AvailableLanguageTag) => void) | undefined} */ 
+let _onSetLanguageTag
+
+/**
+ * The project's source language tag.
+ * 
+ * @example
+ *   if (newlySelectedLanguageTag === sourceLanguageTag){
+ *     // do nothing as the source language tag is the default language
+ *     return
+ *   }
+ */
+export const sourceLanguageTag = "en"
+
+/**
+ * The project's available language tags.
+ * 
+ * @example 
+ *   if (availableLanguageTags.includes(userSelectedLanguageTag) === false){
+ *     throw new Error("Language tag not available")
+ *   }
+ */
+export const availableLanguageTags = /** @type {const} */ (["en","de"])
+
+/**
+ * Get the current language tag.
+ * 
+ * @example
+ *   if (languageTag() === "de"){
+ *     console.log("Germany 🇩🇪")
+ *   } else if (languageTag() === "nl"){
+ *     console.log("Netherlands 🇳🇱")
+ *   }
+ * 
+ * @type {() => AvailableLanguageTag}
+ */
+export let languageTag = () => sourceLanguageTag
+
+/**
+ * Set the language tag.
+ * 
+ * @example 
+ * 
+ *   // changing to language 
+ *   setLanguageTag("en")
+ * 
+ *   // passing a getter function also works. 
+ *   // 
+ *   // a getter function is useful for resolving a language tag 
+ *   // on the server where every request has a different language tag
+ *   setLanguageTag(() => {
+ *     return request.langaugeTag
+ *   }) 
+ *
+ * @param {AvailableLanguageTag | (() => AvailableLanguageTag)} tag
+ */
+export const setLanguageTag = (tag) => {
+	if (typeof tag === "function") {
+		languageTag = tag
+	} else {
+		languageTag = () => tag
+	}
+	// call the callback function if it has been defined
+	if (_onSetLanguageTag !== undefined) {
+		_onSetLanguageTag(languageTag())
+	}
+}
+
+/**
+ * Set the `onSetLanguageTag()` callback function.
+ *
+ * The function can be used to trigger client-side side-effects such as 
+ * making a new request to the server with the updated language tag, 
+ * or re-rendering the UI on the client (SPA apps).  
+ * 
+ * - Don't use this function on the server (!).
+ *   Triggering a side-effect is only useful on the client because a server-side
+ *   environment doesn't need to re-render the UI. 
+ *     
+ * - The `onSetLanguageTag()` callback can only be defined once to avoid unexpected behavior.
+ * 
+ * @example
+ *   // if you use inlang paraglide on the server, make sure 
+ *   // to not call `onSetLanguageTag()` on the server
+ *   if (isServer === false) {
+ *     onSetLanguageTag((tag) => {
+ *       // (for example) make a new request to the 
+ *       // server with the updated language tag
+ *       window.location.href = `/${tag}/${window.location.pathname}`
+ *     })
+ *   }
+ *
+ * @param {(languageTag: AvailableLanguageTag) => void} fn
+ */
+export const onSetLanguageTag = (fn) => {
+	if (_onSetLanguageTag !== undefined) {
+		throw new Error("@inlang/paraglide-js: The `onSetLanguageTag()` callback has already been defined.\n\nThe `onSetLanguageTag()` callback can only be defined once to avoid unexpected behavior.\n\n 1) Try searching for `onSetLanguageTag()` in your codebase for potential duplicated.\n 2) It might be that your framework is calling `onSetLanguageTag()` multiple times. Try to move the `onSetLanguageTag()` out of the rendering scope like a React component.")
+	}
+	_onSetLanguageTag = fn
+}
+
+// ------ TYPES ------
+
+/**
+ * A language tag that is available in the project.
+ * 
+ * @example
+ *   setLanguageTag(request.languageTag as AvailableLanguageTag)
+ * 
+ * @typedef {typeof availableLanguageTags[number]} AvailableLanguageTag
+ */

package/dist/compiled-output/example-typescript/messages.d.ts

@@ -0,0 +1,7 @@
+export function currentLanguageTag(params: {
+    languageTag: NonNullable<unknown>;
+}): string;
+export function greeting(params: {
+    name: NonNullable<unknown>;
+    count: NonNullable<unknown>;
+}): string;

package/dist/compiled-output/example-typescript/messages.js

@@ -0,0 +1,42 @@
+
+import { languageTag } from "./runtime.js"
+
+
+/**
+ * This message has been compiled by [inlang paraglide](https://inlang.com/marketplace/library.inlang.paraglideJs).
+ *
+ * - Don't edit the message manually. Use the [inlang ide extension](https://inlang.com/marketplace/app.inlang.ideExtension)
+ *   or the [web editor](https://inlang.com/marketplace/app.inlang.editor) to edit the message.
+ * 
+ * - The params are NonNullable<unknown> because inlang can't know the value type of a param (yet).
+ * 
+ * @param {{ languageTag: NonNullable<unknown> }} params
+ * @returns {string}
+ */
+  export const currentLanguageTag = (params) => {
+    const variants = {
+      "en": `The current language tag is "${params.languageTag}".`,
+  "de": `Der aktuelle Sprachtag ist "${params.languageTag}".`
+	}
+	return variants[languageTag()] ?? "currentLanguageTag"
+}
+
+
+/**
+ * This message has been compiled by [inlang paraglide](https://inlang.com/marketplace/library.inlang.paraglideJs).
+ *
+ * - Don't edit the message manually. Use the [inlang ide extension](https://inlang.com/marketplace/app.inlang.ideExtension)
+ *   or the [web editor](https://inlang.com/marketplace/app.inlang.editor) to edit the message.
+ * 
+ * - The params are NonNullable<unknown> because inlang can't know the value type of a param (yet).
+ * 
+ * @param {{ name: NonNullable<unknown>, count: NonNullable<unknown> }} params
+ * @returns {string}
+ */
+  export const greeting = (params) => {
+    const variants = {
+      "en": `Welcome ${params.name}! You have ${params.count} messages.`,
+  "de": `Hallo ${params.name}! Du hast ${params.count} Nachrichten.`
+	}
+	return variants[languageTag()] ?? "greeting"
+}

package/dist/compiled-output/example-typescript/runtime.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The project's source language tag.
+ *
+ * @example
+ *   if (newlySelectedLanguageTag === sourceLanguageTag){
+ *     // do nothing as the source language tag is the default language
+ *     return
+ *   }
+ */
+export const sourceLanguageTag: "en";
+/**
+ * The project's available language tags.
+ *
+ * @example
+ *   if (availableLanguageTags.includes(userSelectedLanguageTag) === false){
+ *     throw new Error("Language tag not available")
+ *   }
+ */
+export const availableLanguageTags: readonly ["en", "de"];
+/**
+ * Get the current language tag.
+ *
+ * @example
+ *   if (languageTag() === "de"){
+ *     console.log("Germany 🇩🇪")
+ *   } else if (languageTag() === "nl"){
+ *     console.log("Netherlands 🇳🇱")
+ *   }
+ *
+ * @type {() => AvailableLanguageTag}
+ */
+export let languageTag: () => AvailableLanguageTag;
+export function setLanguageTag(tag: AvailableLanguageTag | (() => AvailableLanguageTag)): void;
+export function onSetLanguageTag(fn: (languageTag: any) => void): void;
+/**
+ * A language tag that is available in the project.
+ */
+export type AvailableLanguageTag = (typeof availableLanguageTags)[number];