Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/enoy19/svelte-lang

svelte-lang is an i18n library for Svelte that simplifies multilingual support. It offers a straightforward API for managing translations, supports parameterized strings, autocompletion, and integrates with Svelte stores for reactive language handling. Features include automatic language detection, making it easy to build global applications.
https://github.com/enoy19/svelte-lang

i18n internationalization l10n localization multilingual svelte svelte-library sveltekit

Last synced: 26 days ago
JSON representation

svelte-lang is an i18n library for Svelte that simplifies multilingual support. It offers a straightforward API for managing translations, supports parameterized strings, autocompletion, and integrates with Svelte stores for reactive language handling. Features include automatic language detection, making it easy to build global applications.

Awesome Lists containing this project

README 

        
# svelte-lang



An internationalization (i18n) library for Svelte applications, designed to make multilingual support simple and efficient.



## Features



- **Simple Setup**: Easily integrate with Svelte applications.

- **Template Literal Translations**: Use template literals for translations, keeping code clean and readable.

- **Parameterized Translations**: Support dynamic parameters within translation strings.

- **Language Persistence**: Optionally persist the selected language in [localstorage](https://github.com/joshnuss/svelte-persisted-store).

- **Automatic Language Detection**: Detect user language preferences from the browser.

- **Inline Parameters**: Support inline parameters in translation keys.

- **Svelte Stores Integration**: Uses Svelte stores for reactive language and translation handling.



## Installation



```bash

npm install svelte-lang

```



## How to Use



### Setup Translations



Create translation files for each language in your project.



**Example: English Translations (`en.ts`)**



```typescript

// src/lib/i18n/translations/en.ts

import { t, p } from 'svelte-lang';



export const en = {

  app: t`svelte-lang`,

  'Something went wrong': t`Something went wrong`,

  'Welcome $name': t`Welcome ${p('name')}`

} as const;

```



**Example: German Translations (`de.ts`)**



```typescript

// src/lib/i18n/translations/de.ts

import { t, p } from 'svelte-lang';



export const de = {

  app: t`svelte-lang`,

  'Something went wrong': t`Etwas ist schief gelaufen`,

  'Welcome $name': t`Willkommen ${p('name')}`

} as const;

```



### Initialize i18n



Set up the i18n configuration in your project.



```typescript

// src/lib/i18n/index.ts

import { setupI18n } from 'svelte-lang';

import { en } from './translations/en';

import { de } from './translations/de';



export const translations = {

  en,

  de

} as const;



export const { t, language, supportedLanguages, tUnsafe, initLanguage } = setupI18n(

  translations,

  'en', // Default language

  { languagePersisted: true } // Persist language selection in localstorage

);

```



### Update `app.d.ts`



Ensure that the `language` property is available in the `App.Locals` interface.



```typescript

// src/app.d.ts

declare global {

  namespace App {

    interface Locals {

      language: string;

    }

  }

}



export {};

```



### Implement Language Detection Hook



Use a server hook to detect and set the user's preferred language.



```typescript

// src/hooks.server.ts

import { translations } from '$lib/i18n';

import { i18nHook } from 'svelte-lang';



export const handle = i18nHook(translations, 'en');

```



#### Add to existing Hook



```typescript

// src/hooks.server.ts

import { translations } from '$lib/i18n';

import { i18nHook } from 'svelte-lang';

import { sequence } from '@sveltejs/kit/hooks';

import { anotherHook } from './anotherHook';



// Combine multiple hooks

export const handle = sequence(

  i18nHook(translations, 'en'),

  anotherHook

  // Add more hooks as needed

);

```



### Initialize Language in Layout



Set the initial language in your root layout.



```svelte



  import { initLanguage } from '$lib/i18n';

  import type { LayoutData } from './$types';



  export let data: LayoutData;



  initLanguage(data.language);



```



```typescript

// src/routes/+layout.server.ts

import type { LayoutServerLoad } from './$types';



export const load: LayoutServerLoad = async ({ locals }) => {

  return { language: locals.language };

};

```



### Use Translations in Components



Use the `t` function to retrieve translations in your Svelte components.



```svelte



  import { language, supportedLanguages, t, tUnsafe } from '$lib/i18n';



  let name = 'John';

  let dynamicKey = 'app';

  let inlineParamsKey = 'Welcome $name({"name": "John"})';



  
{$t('app')}



  


    Select Language:

    

      {#each supportedLanguages as lang}

        {lang}

      {/each}

    

  



  


    Name:

    

    
{$t('Welcome $name', { name })}


  



  


    
Dynamic Key Translation:


    Key:

    

    
{$tUnsafe(dynamicKey)}


  



  


    
Inline Parameters:


    Key:

    

    
{$tUnsafe(inlineParamsKey)}


  



```



### Accessing Translations with Parameters



To include dynamic parameters in your translations, use the `p` function when defining translations and pass the parameters when retrieving them.



**Defining a Translation with Parameters**



```typescript

// In your translation file

'Welcome $name': t`Welcome ${p('name')}`,

```



**Retrieving a Translation with Parameters**



```svelte

{$t('Welcome $name', { name: 'Alice' })}


```



## Contributing



Contributions are welcome! Please open an issue or submit a pull request for any bugs or feature requests.



## License



This project is licensed under the MIT License.