VoerkaI18n Internationalization Solution

VoerkaI18n is a framework-agnostic internationalization solution designed for JavaScript/TypeScript applications. Key capabilities include:

• Framework Agnostic: Works with Vue, React, Svelte, SolidJS, and others.
• Automatic Extraction: Scans your code to extract translatable text automatically.
• AI Translation: Integrates with AI services for automated translation.
• Flexible Formats: Supports various translation methods and file formats.
• TypeScript Support: Provides full type safety for developers.

The @VoerkaI18n/cli package provides command-line tools to manage internationalization (i18n) workflows. It is used to perform the following core tasks:

• Initialization: Setting up the i18n configuration and project structure.
• Text Extraction: Scanning your source code to find and extract translatable text strings.
• Compilation: Compiling i18n resources into the required formats for your application runtime.

Namespaces are a tool for organizing translation source files during the development and extraction phase.

1. Extraction Phase: When you run voerkai18n extract, the tool scans the directories specified in your languages/settings.json namespaces configuration. Instead of a single file, it creates separate JSON files in languages/translates/messages/ named after your namespace keys (e.g., routes.json, auth.json).

2. Compilation Phase: When you run voerkai18n compile, the tool automatically merges all these namespace-specific JSON files back into a single structure. This means the concept of namespaces is transparent to the application at runtime; the application consumes the merged output as if no namespaces were used.

When using @voerkai18n/react, keep these behaviors in mind:

• Provider Requirement: You must wrap your application with VoerkaI18nProvider.
• Re-rendering: To ensure components re-render automatically when the language changes, use the useTranslate hook or the Translate component.
• Static Functions: If you use a t function imported directly from your language configuration file (e.g., import { t } from './languages'), it returns a string but will not trigger a re-render when the language changes. You must manually manage updates in those cases.

For larger blocks of text, use the <Translate> component. The extraction tool identifies these components by their id attribute. Extracted paragraphs are saved as HTML files in languages/translates/paragraphs/ named after the component's id. The output file includes metadata comments (id, scope, file, and range) and wraps the content in div tags with language attributes.

<template>
    <div>       
        <Translate id="license">
Copyright (c) [year] [copyright holder]
...
        </Translate>
    </div>
</template>

Output format (languages/translates/paragraphs/license.html):

<!-- 
    id:    license 
    scope:  
    file:  src\License\index.vue 
    rang:  3:8-8:12 
-->
<div language="zh-CN">
版权所有 (c) [年份] [版权持有者]...
</div>
<div language="en-US">
Copyright (c) [year] [copyright holder]...
</div>

The project follows a standard Astro directory layout:

• src/pages/: Contains .astro or .md files. Each file name corresponds to a route in your application.
• src/content/: Houses 'collections' of Markdown and MDX documents. You can use the getCollection() function to retrieve these documents (e.g., from src/content/blog/) and apply type-checking via schemas.
• src/components/: A directory for reusable Astro, React, Vue, Svelte, or Preact components.
• src/layouts/: Contains layout components used to wrap pages.
• public/: Stores static assets like images that should be served as-is.
• astro.config.mjs: The configuration file for the Astro environment.

├── public/
├── src/
│   ├── components/
│   ├── content/
│   ├── layouts/
│   └── pages/
├── astro.config.mjs
├── README.md
├── package.json
└── tsconfig.json

@voerkai18n/runtime is the core runtime dependency required by the main voerkai18n package. While you typically interact with the high-level voerkai18n package, @voerkai18n/runtime provides the underlying execution logic at runtime.

Key details:

• It is published in multiple transpiled formats to ensure compatibility: commonjs, esm, and iife.
• Best Practice: Always keep @voerkai18n/runtime updated to the latest version to ensure compatibility with the main voerkai18n package and to receive the latest runtime improvements.

In a multi-library scenario, the language configuration of the entire application is governed by the i18nScope instances where library is set to false.

• An application should ideally have only one i18nScope with library: false.
• If multiple i18nScopes with library: false exist, the last one defined takes precedence for the application's language configuration.