Skip to content
jdbruxellesPublic

About

A simple and lightweight package to integrate internationalization on a small website.

Topics

Resources

Stars

3 stars

Watchers

1 watching

Forks

Repository files navigation

Netlify Status npm version wakatime Crowdin jsDelivr

si18n.js

A simple and lightweight way to integrate internationalization on a small web site project.

The "s" in si18n stands for simple.

Fast Lightweight No dependencies Easy to use
Yes Yes Yes Yes

Demo and Documentation

Installation

npm

npm i si18n.js

then use the browser-ready Si18n class:

import Si18n from "si18n.js";

yarn

yarn add si18n.js

CDN

<!-- jsDelivr (recommended) -->
<script type="module" src="https://cdn.jsdelivr.net/npm/si18n.js@latest/si18n.js"></script>
<!-- minified -->
<script type="module" src="https://cdn.jsdelivr.net/npm/si18n.js@latest/si18n.min.js"></script>

<!-- UNPKG -->
<script type="module" src="https://unpkg.com/si18n.js@latest/si18n.js"></script>
<script type="module" src="https://unpkg.com/si18n.js@latest/si18n.min.js"></script>

Node.js

npm i si18n.js

then use the dedicated Node.js export:

const { Si18nNode: Si18n } = require("si18n.js/node");

TypeScript

npm i si18n.js

then import the subpath that matches your runtime:

import Si18nBrowser from "si18n.js/browser";
import Si18nNode from "si18n.js/node";
import { Si18nCore } from "si18n.js/core";

React (Client and Server)

npm i si18n.js react

Client-side provider and hook:

"use client";

import Si18nBrowser from "si18n.js/browser";
import { Si18nProvider, useTranslation } from "si18n.js/react";

const i18n = new Si18nBrowser();

function Content() {
  const { t, locale, setLocale } = useTranslation();

  return (
    <>
      <h1>{t("title")}</h1>
      <button onClick={() => void setLocale(locale === "en" ? "fr" : "en")}>Switch</button>
    </>
  );
}

export default function App() {
  return (
    <Si18nProvider
      i18n={i18n}
      options={{
        locales: {
          en: { title: "Hello" },
          fr: { title: "Bonjour" }
        },
        lang: "en",
        fallbackLang: "en"
      }}
    >
      <Content />
    </Si18nProvider>
  );
}

Server-side helper:

import { createServerTranslator } from "si18n.js/react/server";

const { t } = await createServerTranslator({
  locales: {
    en: { title: "Hello" },
    fr: { title: "Bonjour" }
  },
  lang: "en",
  fallbackLang: "en"
});

console.log(t("title"));

Note

For detailed usage information, demos, and the full API reference, visit the docs.

Run locally

The following instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Requirements

Clone the repo

git clone git@github.com:jdbruxelles/si18n.js.git

Install the dependencies

npm install

Build Commands

  • Run the build process
npm run build
  • Run tests
npm test
  • Watch files during development
npm run watch

npm Publishing

Automated publishing is handled via GitHub Actions with SLSA build provenance attestation.

To release a new version:

  1. Update "version" in package.json and update CHANGELOG.md.
  2. Verify tests and tarball contents locally:
    npm test
    npm run pack:check
  3. Commit, push to main, and create a GitHub Release with a matching tag (e.g. v2.0.0).
  4. The release workflow automatically builds, tests, verifies tag parity, and publishes to npm with provenance.

For configuration details and emergency manual publishing, see .github/workflows/README.md.

Server

For the server, you can use any server you want, but I recommend using http-server. It's a simple zero-configuration command-line http server. I personally use the python http.server or the server provided by netlify-cli to work locally.

Contributing

Contributions are always welcome! For major changes, please open an issue first to discuss what you would like to change.

Translation

You can help translate the application by using Crowdin.

All translations are stored in the website/locales directory. Under no circumstances should you edit the files in this directory, except for the fr.json file which is the source language for the translations.

Translations will be available on the app if they exceed a certain threshold of completion (currently 90%).

Licence

MIT License

About

A simple and lightweight package to integrate internationalization on a small website.

Topics

Resources

Stars

3 stars

Watchers

1 watching

Forks

Releases

Sponsor this project

Used by

Contributors

Languages