@inlang/paraglide-js 1.3.5 → 1.3.7

package/README.md

@@ -1,33 +1,44 @@
-[<img src="https://cdn.loom.com/sessions/thumbnails/a8365ec4fa2c4f6bbbf4370cf22dd7f6-with-play.gif" width="100%" /> Watch the demo of Paraglide JS](https://www.youtube.com/watch?v=-YES3CCAG90)
+[<img src="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/header.png" alt="Dead Simple i18n. Typesafe, Small Footprint, Treeshsakeable Messages, IDE Integration, Framework Agnostic" width="10000000px" />](https://www.youtube.com/watch?v=-YES3CCAG90)
 
-<!-- ![Paraglide JS header image](https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/paraglide-js-header.png) -->
+# Why Paraglide?
 
-Get started with:
+<doc-features>
+  <doc-feature title="Tiny Runtime" image="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/bundlesize-feature.png"></doc-feature>
+  <doc-feature title="Fully Typesafe" image="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/typesafety-feature.png"></doc-feature>
+  <doc-feature title="Only Ship Used Messages" image="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/unused-translations.png"></doc-feature>
+   <doc-feature title="Sherlock VsCode Extension" image="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/sherlock-preview.png"></doc-feature>
+</doc-features>
 
-```bash
-npx @inlang/paraglide-js@latest init
-```
 
-# Features
+With Paraglide's Treeshsakeable messages, each page only loads the messages it actually uses. Incremental loading like this would usually take forever to get right, with Paraglide you get it for free.
 
-<doc-features>
-  <doc-feature title="Only used translations are shipped" image="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/unused-translations.png"></doc-feature>
-  <doc-feature title="Tiny Bundle-Size" image="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/reduced-payload.png"></doc-feature>
-  <doc-feature title="Typesafe" image="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/typesafe.png"></doc-feature>
-</doc-features>
+# Use it with your Favorite Framework
 
-### Treeshaking
+Paraglide is framework agnostic, but it's even better if you pair it with a framework specific library. If you are using one of these frameworks you will want to follow the framework specific documentation instead. If you aren't, that's fine too! You can read on.
 
-<doc-figure src="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/tree-shaking.jpg" alt="An illustration explaining the benefits of treeshaking in software" caption="How Paraglide JS treeshaking works">
-</doc-figure>
+<doc-links>
+	<doc-link title="Adapter for NextJS" icon="tabler:brand-nextjs" href="/m/osslbuzt/paraglide-next-i18n" description="Go to Library"></doc-link>
+    <doc-link title="Adapter for SvelteKit" icon="simple-icons:svelte" href="/m/dxnzrydw/paraglide-sveltekit-i18n" description="Go to Library"></doc-link>
+    <doc-link title="Adapter for Astro" icon="devicon-plain:astro" href="/m/iljlwzfs/paraglide-astro-i18n" description="Go to Library"></doc-link>
+    <doc-link title="Adapter for SolidJS" icon="tabler:brand-solidjs" href="/m/n860p17j/paraglide-solidstart-i18n" description="Go to Library"></doc-link>
+	<doc-link title="Adapter for Remix" icon="simple-icons:remix" href="/m/fnhuwzrx/paraglide-remix-i18n" description="Go to Library"></doc-link>
+	<doc-link title="Or write your own" icon="ph:sparkle-fill" href="#writing-an-adapter" description="Learn How"></doc-link>
+</doc-links>
 
-Treeshaking gives us superpowers. With it, each page of your app only loads the messages that it actually uses. Incremental loading like this would usually take hours of manual tweaking to get right. With Paraglide-JS you get it for free. Say goodbye to huge bundles.
+# People Love It
 
-# Getting started
+Here are a few comments we've received recently.
 
-### 1. Initialize paraglide-js
+<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>
+<doc-comment text="I was messing with various i18n frameworks and tools in combination with Astro, and i must say that Paraglide was the smoothest experience. I have migrated my website from i18next and it was a breeze. SSG and SSR worked out of the box (which was the first one for me), and overall DX is great. Thanks for your work!" author="Dalibor Hon" icon="mdi:discord" data-source="https://discord.com/channels/897438559458430986/1096039983116202034/1220796380772307004"></doc-comment>
+<doc-comment text="The lib is great guys!" author="ktarmyshov" icon="mdi:github"></doc-comment>
+<doc-comment text="Thank you for that huge work you have done and still doing!" author="ZerdoX-x" icon="mdi:github"></doc-comment>
+</doc-comments>
+
+# Getting started
 
-Initialize ParaglideJS whith:
+To use Paraglide stanadlone without a framework, run the following command:
 
 ```bash
 npx @inlang/paraglide-js@latest init
@@ -35,41 +46,36 @@ npx @inlang/paraglide-js@latest init
 
 This will:
 
-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-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="/m/osslbuzt/library-inlang-paraglideJsAdapterNextJs" description="Go to Library"></doc-link>
-    <doc-link title="Adapter for SvelteKit" icon="simple-icons:svelte" href="/m/dxnzrydw/library-inlang-paraglideJsAdapterSvelteKit" description="Go to Library"></doc-link>
-    <doc-link title="Adapter for Astro" icon="devicon-plain:astro" href="/m/iljlwzfs/library-inlang-paraglideJsAdapterAstro" description="Go to Library"></doc-link>
-    <doc-link title="Adapter for SolidJS" icon="tabler:brand-solidjs" href="/m/n860p17j/library-inlang-paraglideJsAdapterSolidStart" description="Go to Library"></doc-link>
-</doc-links>
-
-#### Alternatively, [you can write your own adapter](#writing-an-adapter)
-
-# Usage
+- Install necessary dependencies
+- Generate a `messages/` folder where your translation files live
+- Add the Paraglide compiler to your `build` script
+- Create necessary configuration files
 
-Running your `build` script will generate a `src/paraglide` folder. This folder contains all the code that you need to use paraglide-js.
+Running the paraglide compiler will generate a `src/paraglide` folder. This folder contains all the code that you need to use paraglide-js.
 
-## Adding Messages
+## Adding and Editing Messages
 
-By default, paraglide expects your messages to be in `messages/{lang}.json`.
+Messages are stored in `messages/{lang}.json`. To add a message simply add a key-value pair. You can add parameters with curly braces.
 
-```json
+```diff
+// messages/en.json
 {
-	"hello": "Hello world!"
-	"loginHeader": "Hello {name}, please login to continue."
+	"$schema": "https://inlang.com/schema/inlang-message-format",
++ 	"greeting": "Hello {name}!"
 }
 ```
 
-## Using Messages
+Make sure to re-run the paraglide compiler after editing your messages.
 
-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.
+```
+npx @inlang/paraglide-js compile --project ./project.inlang
+```
+
+If you are using Vite, you can instead use the [paraglide vite-plugin](https://github.com/opral/monorepo/tree/main/inlang/source-code/paraglide/paraglide-js-adapter-vite) to do this automatically.
+
+## Using Messages in Code
+
+After running the compiler, you can import messages with `import * as m from "./paraglide/messages"`.
 
 ```js
 import * as m from "./paraglide/messages.js"
@@ -79,7 +85,7 @@ m.hello() // Hello world!
 m.loginHeader({ name: "Samuel" }) // Hello Samuel, please login to continue.
 ```
 
-If you want to choose between messages at runtime, you can create a record of messages and index into it.
+To choose between messages at runtime create a map of messages and index into it.
 
 ```ts
 import * as m from "./paraglide/messages.js"
@@ -94,15 +100,14 @@ const season = {
 const msg = season["spring"]() // Hello spring!
 ```
 
-### Using the [Sherlock IDE Extension](https://inlang.com/m/r7kp499g/app-inlang-ideExtension) (optional)
-
-[Sherlock](https://inlang.com/m/r7kp499g/app-inlang-ideExtension) integrates with paraglide to give you the optimal dev-experience.
+## Configuration
 
-![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)
+You can configure the languages you intend to support
 
-## Adding Languages
+### Languages
 
 You can declare which languages you support in `./project.inlang/settings.json`.
+
 ```json
 // project.inlang/settings.json
 {
@@ -268,21 +273,25 @@ An "Adapter" is a library that integrates with a framework's liefcycle and does
 This example adapts Paraglide to a fictitious fullstack framework.
 
 ```tsx
-import { setLanguageTag, onSetLanguageTag, type AvailableLanguageTag } from "../paraglide/runtime.js"
+import {
+	setLanguageTag,
+	onSetLanguageTag,
+	type AvailableLanguageTag,
+} from "../paraglide/runtime.js"
 import { isServer, isClient, request, render } from "@example/framework"
 import { detectLanguage } from "./utils.js"
 
 if (isServer) {
-	// On the server the language tag needs to be resolved on a per-request basis. 
+	// On the server the language tag needs to be resolved on a per-request basis.
 	// Pass a getter function that resolves the language from the correct request
 
-	const detectLanguage = (request: Request) : AvailableLanguageTag => {
+	const detectLanguage = (request: Request): AvailableLanguageTag => {
 		//your logic ...
 	}
 	setLanguageTag(() => detectLanguage(request))
 }
 
-if(isClient) {
+if (isClient) {
 	// On the client, the language tag can be resolved from
 	// the document's html lang tag.
 	setLanguageTag(() => document.documentElement.lang)
@@ -304,20 +313,6 @@ render((page) => (
 ))
 ```
 
-# Community
-
-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>
-<doc-comment text="I was messing with various i18n frameworks and tools in combination with Astro, and i must say that Paraglide was the smoothest experience. I have migrated my website from i18next and it was a breeze. SSG and SSR worked out of the box (which was the first one for me), and overall DX is great. Thanks for your work!" author="Dally H" icon="mdi:discord" data-source="https://discord.com/channels/897438559458430986/1096039983116202034/1220796380772307004"></doc-comment>
-<doc-comment text="The lib is great guys!" author="ktarmyshov" icon="mdi:github"></doc-comment>
-<doc-comment text="Thank you for that huge work you have done and still doing!" author="ZerdoX-x" icon="mdi:github"></doc-comment>
-<doc-comment text="Thanks for all the great work @Samuel Stroschein" author="Willem" icon="mdi:discord"></doc-comment>
-</doc-comments>
-
 # Roadmap
 
 Of course, we're not done yet! We plan on adding the following features to Paraglide JS soon:
@@ -325,6 +320,7 @@ Of course, we're not done yet! We plan on adding the following features to Parag
 - [ ] 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))
 - [ ] Markup Placeholders ([Join the Discussion](https://github.com/opral/monorepo/discussions/913))
+- [ ] Even Smaller Output
 
 # Talks
 
@@ -337,7 +333,7 @@ Of course, we're not done yet! We plan on adding the following features to Parag
 
 Paraglide JS is part of the Inlang ecosystem and integrates nicely with all the other Inlang compatible tools.
 
-As a developer, you will love the [Sherlock IDE extension](http://localhost:4001/m/r7kp499g/app-inlang-ideExtension).
+As a developer, you will love the [Sherlock VsCode extension](https://inlang.com/m/r7kp499g/app-inlang-ideExtension).
 
 If you are working with translators or designers you will find these tools useful:
 

package/dist/cli/commands/{init.d.ts → init/command.d.ts}

@@ -1,13 +1,17 @@
 import { Command } from "commander";
-import { type ProjectSettings } from "@inlang/sdk";
-import { Logger } from "../../services/logger/index.js";
+import { type InlangProject } from "@inlang/sdk";
+import { Logger } from "../../../services/logger/index.js";
 import { type Repository } from "@lix-js/client";
 type Context = {
     logger: Logger;
     repo: Repository;
 };
 export declare const initCommand: Command;
-export declare const initializeInlangProject: (ctx: Context) => Promise<string>;
+export declare const initializeInlangProject: (ctx: Context) => Promise<{
+    project: InlangProject;
+    /** Relative path to the project */
+    projectPath: string;
+}>;
 export declare const maybeAddVsCodeExtension: (args: {
     projectPath: string;
 }, ctx: Context) => Promise<void>;
@@ -15,13 +19,13 @@ export declare const addParaglideJsToDevDependencies: (ctx: Context) => Promise<
 export declare const findExistingInlangProjectPath: (ctx: Context) => Promise<string | undefined>;
 export declare const existingProjectFlow: (args: {
     existingProjectPath: string;
-}, ctx: Context) => Promise<undefined>;
-export declare const createNewProjectFlow: (ctx: Context) => Promise<undefined>;
-export declare const newProjectTemplate: ProjectSettings;
+}, ctx: Context) => Promise<InlangProject>;
+export declare const createNewProjectFlow: (ctx: Context) => Promise<InlangProject>;
 export declare const checkIfPackageJsonExists: (ctx: Context) => Promise<undefined>;
 export declare const checkIfUncommittedChanges: (ctx: Context) => Promise<void>;
 export declare const addCompileStepToPackageJSON: (args: {
     projectPath: string;
+    outdir: string;
 }, ctx: Context) => Promise<undefined>;
 /**
  * Ensures that the moduleResolution compiler option is set to "bundler" or similar in the tsconfig.json.

package/dist/cli/commands/init/defaults.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @returns A new copy of the default project template that is safe to mutate.
+ */
+export declare function getNewProjectTemplate(): {
+    $schema: "https://inlang.com/schema/project-settings";
+    sourceLanguageTag: string;
+    languageTags: string[];
+    modules: string[];
+    "plugin.inlang.messageFormat": {
+        pathPattern: string;
+    };
+};
+export declare const DEFAULT_PROJECT_PATH = "./project.inlang";
+export declare const DEFAULT_OUTDIR = "./src/paraglide";

package/dist/cli/commands/init/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Executes a command asynchronously in a separate process.
+ * It will not print the output to the console.
+ *
+ * @param command The command to execute.
+ * @returns The stdout of the command.
+ */
+export declare function execAsync(command: string): Promise<string>;