Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
@inlang/paraglide-js
Advanced tools
@inlang/paraglide-js - npm Package Compare versions
Comparing version 1.3.3 to 1.3.4
| { | ||
| "name": "@inlang/paraglide-js", | ||
| "type": "module", | ||
| "version": "1.3.3", | ||
| "version": "1.3.4", | ||
| "license": "Apache-2.0", | ||
@@ -10,7 +10,6 @@ "publishConfig": { | ||
| "author": "inlang <hello@inlang.com> (https://inlang.com/)", | ||
| "homepage": "https://github.com/opral/monorepo/tree/main/inlang/source-code/paraglide/paraglide-js", | ||
| "homepage": "https://inlang.com/m/gerre34r/library-inlang-paraglideJs", | ||
| "repository": { | ||
| "type": "git", | ||
| "url": "https://github.com/opral/monorepo.git", | ||
| "directory": "inlang/source-code/paraglide/paraglide-js" | ||
| "url": "https://github.com/opral/inlang-paraglide-js" | ||
| }, | ||
@@ -49,3 +48,2 @@ "keywords": [ | ||
| "dedent": "1.5.1", | ||
| "isomorphic-git": "1.24.5", | ||
| "json5": "2.2.3", | ||
@@ -68,9 +66,9 @@ "posthog-node": "3.1.3", | ||
| "vitest": "0.34.3", | ||
| "@inlang/env-variables": "0.2.0", | ||
| "@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/env-variables": "0.2.0", | ||
| "@inlang/sdk": "0.28.2", | ||
| "@lix-js/client": "1.1.0", | ||
| "@inlang/telemetry": "0.3.17", | ||
| "@lix-js/fs": "1.0.0", | ||
| "@inlang/plugin-message-format": "2.1.1" | ||
@@ -77,0 +75,0 @@ }, |
173
README.md
@@ -5,4 +5,2 @@ [<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) | ||
| # Simple, adaptable, and tiny i18n library for JS | ||
| Get started with: | ||
@@ -17,5 +15,5 @@ | ||
| <doc-features> | ||
| <doc-feature title="No unused translations" image="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/unused-translations.png"></doc-feature> | ||
| <doc-feature title="Minimal payload" image="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/reduced-payload.png"></doc-feature> | ||
| <doc-feature title="Typesafety" image="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/inlang/source-code/paraglide/paraglide-js/assets/typesafe.png"></doc-feature> | ||
| <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> | ||
@@ -34,3 +32,3 @@ | ||
| Initialize paraglide-js whith: | ||
| Initialize ParaglideJS whith: | ||
@@ -52,6 +50,6 @@ ```bash | ||
| <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> | ||
| <doc-link title="Adapter for SvelteKit" icon="simple-icons:svelte" href="https://inlang.com/m/dxnzrydw/library-inlang-paraglideJsAdapterSvelteKit" description="Go to Library"></doc-link> | ||
| <doc-link title="Adapter for SolidJS" icon="tabler:brand-solidjs" href="https://inlang.com/m/n860p17j/library-inlang-paraglideJsAdapterSolidStart" description="Go to Library"></doc-link> | ||
| <doc-link title="Adapter for Vite" icon="tabler:brand-vite" href="https://github.com/opral/monorepo/tree/main/inlang/source-code/paraglide/paraglide-js-adapter-vite" description="Go to GitHub"></doc-link> | ||
| <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> | ||
@@ -65,7 +63,6 @@ | ||
| > 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`. | ||
| By default, paraglide expects your messages to be in `messages/{lang}.json`. | ||
| ```json | ||
@@ -100,3 +97,3 @@ { | ||
| winter: m.winter, | ||
| } as const; | ||
| } as const | ||
@@ -106,7 +103,6 @@ const msg = season["spring"]() // Hello spring! | ||
| ### Using the [Sherlock IDE Extension](https://inlang.com/m/r7kp499g/app-inlang-ideExtension) (optional) | ||
| ### (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. | ||
| [Sherlock](https://inlang.com/m/r7kp499g/app-inlang-ideExtension) integrates with paraglide to give you the optimal dev-experience. | ||
|  | ||
@@ -116,4 +112,3 @@ | ||
| You can declare which languages you support in `./project.inlang/settings.json` in the `languageTags` array. | ||
| You can declare which languages you support in `./project.inlang/settings.json`. | ||
| ```json | ||
@@ -172,3 +167,3 @@ // project.inlang/settings.json | ||
| 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. | ||
| You can import a message in a specific language from `paraglide/messages/{lang}.js`. | ||
@@ -180,3 +175,3 @@ ```ts | ||
| 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. | ||
| If you want to force a language, but don't know _which_ language ahead of time you can pass the `languageTag` option as the second parameter to a message function. This is often handy on the server. | ||
@@ -188,3 +183,3 @@ ```js | ||
| ## Lazy-Loading | ||
| ## Lazy-Loading | ||
@@ -194,6 +189,7 @@ Paraglide consciously discourages lazy-loading translations since it seriously hurts | ||
| 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. | ||
| If you _really_ want to do it anway, you can lazily import the language-specific message files. Be careful with this. | ||
| ```ts | ||
| const lazyGerman = await import("./paraglide/messages/de.js") | ||
| lazyGerman.hello() // Hallo Welt | ||
| ``` | ||
@@ -203,14 +199,13 @@ | ||
| We provide bundler plugins to make it easier to use Paraglide with a bundler. If you | ||
| are using one we recommed using the corresponding plugin. | ||
| If you are using a bundler you should use the corresponding plugin. The plugin will keep your message-functions up-to-date by compiling whenever your messages change and before build. | ||
| - [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) | ||
| <doc-links> | ||
| <doc-link title="Vite Plugin" icon="tabler:brand-vite" href="https://github.com/opral/monorepo/tree/main/inlang/source-code/paraglide/paraglide-js-adapter-vite" description="Go to Github"></doc-link> | ||
| <doc-link title="Rollup Plugin" icon="file-icons:rollup" href="https://github.com/opral/monorepo/tree/main/inlang/source-code/paraglide/paraglide-js-adapter-rollup" description="Go to Github"></doc-link> | ||
| <doc-link title="Webpack Plugin" icon="mdi:webpack" href="https://github.com/opral/monorepo/tree/main/inlang/source-code/paraglide/paraglide-js-adapter-webpack" description="Go to Github"></doc-link> | ||
| </doc-links> | ||
| 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). | ||
| Find examples for how to use paraglide on codesandbox or in [our GitHub repository](https://github.com/opral/monorepo/tree/main/inlang/source-code/paraglide). | ||
@@ -225,9 +220,13 @@ <doc-links> | ||
| Inlang Paraglide JS leverages a compiler to emit vanilla JavaScript functions. | ||
| ParaglideJS leverages a compiler to generate vanilla JavaScript functions from your messages. We call these "message functions". | ||
| The emitted functions are referred to as "message functions". By emitting message functions, inlang Paraglide JS eliminates a whole 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 300 bytes minified & gzipped. | ||
| Message Functions are fully typed using JSDoc. They are exported individually from the `messages.js` file making them tree-shakable. They aren't reactive, they just return a string. | ||
| This avoids many edge cases associated with reactivity, lazy-loading and namespacing that other i18n libraries have to work around. | ||
| In addition to the message functions, ParaglideJS also emits a runtime. The runtime is used to set the language tag. It contains less than 50 LOC (lines of code) and is less than 300 bytes minified & gzipped. | ||
|  | ||
| Inlang Paraglide-JS consists of four main parts: | ||
| Paraglide consists of four main parts: | ||
@@ -243,6 +242,4 @@ | Part | Description | | ||
| The compiler loads an inlang project and compiles the messages into tree-shakable and typesafe message functions. | ||
| The compiler loads an Inlang project and compiles the messages into tree-shakable and typesafe message functions. | ||
| #### Example | ||
| **Input** | ||
@@ -253,4 +250,3 @@ | ||
| { | ||
| "hello": "Hello {name}!", | ||
| "loginButton": "Login" | ||
| "hello": "Hello {name}!" | ||
| } | ||
@@ -269,5 +265,2 @@ ``` | ||
| export const hello = (params) => `Hello ${params.name}!` | ||
| /** ... */ | ||
| export const loginButton = () => "Login" | ||
| ``` | ||
@@ -277,77 +270,43 @@ | ||
| The compiled messages are importable as a namespace import (`import * as m`). | ||
| By convention we import the compiled funcitions with a wildcard import. | ||
| 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 exist in an example project. | ||
| ```js | ||
| // src/paraglide/messages.js | ||
| /** ... */ | ||
| export const hello = (params) => `Hello ${params.name}!` | ||
| /** ... */ | ||
| export const loginButton = () => "Login" | ||
| /** ... */ | ||
| export const loginHeader = (params) => `Hello ${params.name}, please login to continue.` | ||
| ``` | ||
| Only the message `hello` is used in the source code. | ||
| ```js | ||
| // src/my-code.js | ||
| import * as m from "../paraglide/messages.js" | ||
| console.log(m.hello({ name: "Samuel" })) | ||
| ``` | ||
| The bundler tree shakes (removes) `loginButton` and `loginHeader` and only includes `hello` in the output. | ||
| Bundlers like Rollup, Webpack, or Turbopack tree-shake the messages that are not used, so using a wildcard import is perfectly fine. | ||
| ```js | ||
| // dist/my-code.js | ||
| const hello = (params) => `Hello ${params.name}!` | ||
| console.log(hello({ name: "Samuel" })) | ||
| ``` | ||
| # Writing an Adapter | ||
| An "adapter" is a library that integrates with a framework's liefcycle and does two main things: | ||
| An "Adapter" is a library that integrates with a framework's liefcycle and does two things: | ||
| - Calls `setLanguageTag()` at appropriate times to set the language | ||
| - Reacts to `onSetLanguageTag()`, usually by navigating or relading the page. | ||
| 1. Calls `setLanguageTag()` at appropriate times to set the language | ||
| 2. Reacts to `onSetLanguageTag()`, usually by navigating or relading the page. | ||
| Here is an example that adapts Paraglide-JS to a fictitious metaframework like NextJS or SvelteKit. | ||
| This example adapts Paraglide to a fictitious fullstack framework. | ||
| ```tsx | ||
| import { setLanguageTag, onSetLanguageTag } from "../paraglide/runtime.js" | ||
| import { isServer, request, render } from "@example/framework" | ||
| import { setLanguageTag, onSetLanguageTag, type AvailableLanguageTag } from "../paraglide/runtime.js" | ||
| import { isServer, isClient, request, render } from "@example/framework" | ||
| import { detectLanguage } from "./utils.js" | ||
| // 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 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 => { | ||
| //your logic ... | ||
| } | ||
| setLanguageTag(() => detectLanguage(request)) | ||
| } | ||
| // 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 { | ||
| if(isClient) { | ||
| // On the client, the language tag can be resolved from | ||
| // the document's html lang tag. | ||
| 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 | ||
| // When the language changes we want to re-render the page in the new language | ||
| // Here we just navigate to the new route | ||
| // | ||
| // Make sure to call `onSetLanguageTag` after `setLanguageTag` to avoid an infinite loop. | ||
| onSetLanguageTag((newLanguageTag) => { | ||
@@ -358,3 +317,3 @@ window.location.pathname = `/${newLanguageTag}${window.location.pathname}` | ||
| // make sure the app renders _after_ you've done your setup | ||
| // Render the app once the setup is done | ||
| render((page) => ( | ||
@@ -369,3 +328,3 @@ <html lang={request.languageTag}> | ||
| We are grateful for all the support we get from the community. Here are a few comments we've received recently. | ||
| We are grateful for all the support we get from the community. Here are a few comments we've received recently. | ||
@@ -376,5 +335,5 @@ If you have any feedback / problems, please let us know on [GitHub](https://github.com/opral/inlang-paraglide-js/issues/new) | ||
| <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="[...] the switch between the sdk-js and paraglide has been pretty great! " author="albbus" icon="mdi:discord"></doc-comment> | ||
| <doc-comment text="Thanks for all the great work @Samuel Stroschein" author="Willem" icon="mdi:discord"></doc-comment> | ||
@@ -398,6 +357,10 @@ </doc-comments> | ||
| # Working with Translators | ||
| # Tooling | ||
| Paraglide JS is part of the inlang ecosystem, so it integrates nicely with all the other inlang compatible tools. If you are working with translators and/or designers you will find the following tools useful: | ||
| 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). | ||
| If you are working with translators or designers you will find these tools useful: | ||
| - [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. | ||
@@ -404,0 +367,0 @@ - [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. |
Sorry, the diff of this file is too big to display
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by29.66%
2049381
- Dependency count
- decreased by-14.29%
6
- Lines of code
- increased by39.83%
56757
Worsened metrics
- Number of lines in readme file
- decreased by-9.56%
350
Dependency changes
- Removedisomorphic-git@1.24.5
- Removedasync-lock@1.4.1(transitive)
- Removedclean-git-ref@2.0.1(transitive)
- Removedcrc-32@1.2.2(transitive)
- Removeddecompress-response@6.0.0(transitive)
- Removeddiff3@0.0.3(transitive)
- Removedignore@5.3.2(transitive)
- Removedinherits@2.0.4(transitive)
- Removedisomorphic-git@1.24.5(transitive)
- Removedmimic-response@3.1.0(transitive)
- Removedminimist@1.2.8(transitive)
- Removedminimisted@2.0.1(transitive)
- Removedonce@1.4.0(transitive)
- Removedpako@1.0.11(transitive)
- Removedpify@4.0.1(transitive)
- Removedreadable-stream@3.6.2(transitive)
- Removedsafe-buffer@5.2.1(transitive)
- Removedsha.js@2.4.11(transitive)
- Removedsimple-concat@1.0.1(transitive)
- Removedsimple-get@4.0.1(transitive)
- Removedstring_decoder@1.3.0(transitive)
- Removedutil-deprecate@1.0.2(transitive)
- Removedwrappy@1.0.2(transitive)