open-index/open-npm huggingface dataset:
npm package: @localey/cli
Description: **Localization that feels like TypeScript.**
Latest version: 0.1.26

# 🧩 Localey

**Localization that feels like TypeScript.**

Localey is a high-precision, component-centric localization engine designed for modern web and mobile apps. It automates the extraction of hardcoded strings, generates semantic translation keys using AI, and ensures 100% type safety.

## 🚀 Recent Features (v0.1.21)

### 🎯 High-Precision Extraction

- **Technical Noise Filtering**: Automatically skips HEX colors (`#ffffff`), CSS units (`10px`, `1rem`), numbers, and technical constants.
- **Smart Scoping**: Automatically generates component-scoped keys (e.g., `LoginForm.SUBMIT`).
- **Context-Aware Fallbacks**: Intelligently uses semantic folder names for Next.js/Expo routes (skipping generic names like `app` or `index`).

### 🛠️ Developer Control

- **`ignoreAttributes`**: Blacklist custom props from extraction in your `localey.config.json`.
- **`/* localey-ignore */`**: Skip specific lines or elements with a simple comment.
- **Type-Safe Injection**: Automatically adds `as any` to `t()` calls in JSX props to satisfy strict TypeScript union types.

### 🤖 AI-Powered Workflow

- **`ai.auto`**: Enable AI in your config, and Localey will automatically use it for every extraction.
- **Improved Context**: Uses JSX parent components (like `Button`, `Text`) to decide on prefixes (`BTN_`, `LBL_`).
- **Diagnostic Logging**: Clear feedback in the console if your AI configuration is missing or invalid.

## 📦 Installation

```bash
npm install -g @localey/cli
```

## 🛠️ Getting Started

### 1. Initialize

```bash
localey setup
```

This generates `localey.config.json` and sets up your i18n infrastructure.

### 2. Configure (Optional)

Add your AI key and custom exclusions to `localey.config.json`:

```json
{
  "frameworks": ["react"],
  "ignoreAttributes": ["rightIcon", "headerLeft"],
  "ai": {
    "provider": "openai",
    "apiKey": "sk-...",
    "auto": true
  }
}
```

### 3. Extract & Sync

```bash
localey extract --dir ./src
```

Or use the real-time watcher:

```bash
localey dev --dir ./src
```

## 📜 Manual Control

Want to skip a specific string?

```tsx
<Text>{/* localey-ignore */}Not for translation</Text>
<div className="bg-[#ea580c]" /> // Automatically skipped
```

## 📄 License

MIT
npm package: @localey/core
Description: The central orchestration logic for the Localey ecosystem.
Latest version: 0.1.26

# @localey/core

The central orchestration logic for the Localey ecosystem.

The `@localey/core` package contains the fundamental abstractions and services required to run Localey's automated localization workflows. It is designed to be framework-agnostic and highly extensible.

## Architecture and Services

### Configuration Management

The `ConfigLoader` service is responsible for discovering, parsing, and validating project-specific configurations. It provides a unified configuration object used by the CLI and all registered adapters.

### Plugin Architecture

Localey utilizes a registry-based plugin system managed by the `PluginRegistry`. This allows framework-specific functionality to be decoupled from the core engine. Each adapter registers its supported file extensions and scanning capabilities with this central registry.

### Adapter Abstraction

The `FrameworkAdapter` is an abstract base class that defines the contract for framework-specific implementations. Any developer wishing to extend Localey to support a new framework (e.g., Vue or Angular) should implement this interface.

## Core API Reference

- `ConfigLoader.load(cwd: string)`: Retrieves the effective configuration for a given working directory.
- `PluginRegistry.register(adapter: FrameworkAdapter)`: Adds a new adapter to the system.
- `LocaleyConfig`: TypeScript interface defining the structure of the configuration file.
- `ScanResult`: Standardized data structure for representing a discovered hardcoded string, including its location and context.

## Implementation Details

The core package ensures that file system operations are handled consistently across different platforms. It also provides the logical foundation for the `check` command, implementing deep-object flattening and key comparison algorithms used for translation validation.
npm package: @localey/dart
Description: Localey runtime for Flutter/Dart
Latest version: 0.1.26

# @localey/dart

Dart and Flutter Runtime SDK for Localey.

The `@localey/dart` package provides the runtime localization engine for Flutter applications. It facilitates efficient string lookups and interpolation within the Dart environment, maintaining a single source of truth for translations across platforms.

## Initialization

The SDK should be initialized at the application entry point (typically the `main()` function).

```dart
import 'package:localey/localey.dart';

void main() {
  Localey.init(
    translations: {
      'common': {
        'confirm': 'OK',
        'cancel': 'Cancel'
      }
    }
  );
}
```

## Runtime Global API

The `Localey` class provides a static interface for localization.

### t(String key, [Map<String, dynamic>? params])

The primary method for resolving translation keys.

- **Dot Notation**: Supports hierarchical keys (e.g., `auth.errors.invalid_password`).
- **Dynamic Parameters**: Supports variable replacement within strings using curly brace syntax (e.g., `Hello {user}`).

### Example Usage in a Widget

```dart
Text(Localey.t("common.confirm"))
```

## Features and Integration

- **Dart Implementation**: Pure Dart implementation with no platform-specific dependencies.
- **Nested Object Support**: Deeply nested JSON structures are resolved recursively.
- **Performance**: Optimized for the Flutter build cycle to ensure minimal impact on frame rendering times.
npm package: @localey/flutter
Description: Flutter and Dart adapter for Localey.
Latest version: 0.1.26

# @localey/flutter

Flutter and Dart adapter for Localey.

The `@localey/flutter` package provides localization support for mobile applications developed with Flutter. It utilizes a robust pattern-matching engine designed specifically for Dart's declarative UI syntax.

## Detection and Extraction

Unlike the web-based adapters that use full AST parsers, the Flutter adapter utilizes specialized regular expression patterns tuned for the Dart programming language. This provides high performance and reliable detection for common Flutter widget patterns.

### Target Patterns

- **Text Widgets**: Detects string literals within `Text("...")` constructors.
- **Property Names**: Targets common UI-related properties such as `labelText`, `hintText`, `title`, `tooltip`, and `message`.
- **String Literals**: Identifies standard Dart string literals (single and double quotes) that appear to be user-facing content.

### Code Transformation

When a string is extracted, the adapter replaces the literal with a call to the Localey Dart SDK.

- **Transformation**: `"Hello"` -> `Localey.t("hello")`

## Usage in Flutter Projects

This adapter is automatically engaged when the `flutter` framework is specified in your `localey.config.json`. It scans files with the `.dart` extension and prepares them for use with the shared JSON-based translation files used by the rest of the Localey ecosystem.
npm package: @localey/js
Description: JavaScript and TypeScript Runtime SDK for Localey.
Latest version: 0.1.26

# @localey/js

JavaScript and TypeScript Runtime SDK for Localey.

The `@localey/js` package is an ultra-lightweight, zero-dependency SDK designed to perform string resolution and interpolation at runtime. It is the primary runtime for web applications using React, Svelte, or vanilla JavaScript.

## Setup and Initialization

To use the SDK, you must initialize it with your locale-specific translations.

```typescript
import { init, t } from "@localey/js";
import enTranslations from "./locales/en.json";

init({
  locale: "en",
  translations: enTranslations,
});
```

## Core Functionality

### String Translation

The `t()` function is the primary interface for retrieving localized content. It supports nested key access using dot notation.

```typescript
// For a translation object: { "auth": { "login": "Sign In" } }
t("auth.login"); // Returns: "Sign In"
```

### Parameter Interpolation

The SDK supports dynamic value insertion through a parameter object.

```typescript
// For a translation string: "Hello {name}!"
t("greeting", { name: "Alice" }); // Returns: "Hello Alice!"
```

### Type-Safe Integration

When combined with the Localey CLI's `types` command, you can use generated key maps to ensure that only valid keys are passed to the `t()` function, providing compile-time verification of your localization logic.

## Technical Specifications

- **Performance**: Constant-time lookup for flat objects and efficient traversal for nested structures.
- **Size**: Minimized bundle footprint suitable for high-performance frontend applications.
- **Compatibility**: Compatible with all modern browsers and Node.js environments.
npm package: @localey/react
Description: React and JSX adapter for Localey.
Latest version: 0.1.26

# @localey/react

React and JSX adapter for Localey.

This package provides the logic necessary for Localey to understand and manipulate React source code. It utilizes high-precision Abstract Syntax Tree (AST) traversal to identify hardcoded strings within JSX elements and component properties.

## Detection Logic

The adapter utilizes the `@babel/parser` and `@babel/traverse` packages to analyze source code. It targets specific nodes within the AST that predominantly contain user-facing text.

### Supported Patterns

- **JSX Text Nodes**: Standard text content between opening and closing JSX tags.
- **Component Attributes**: String literals passed to props (e.g., `label`, `title`, `placeholder`).
- **Conditional Strings**: Support for strings within ternary operators and template literals is currently handled via AST inspection.

### Code Transformation

During the `extract` process, this adapter replaces string literals with JSX expression containers.

- **Pattern**: `text` -> `{t("key")}`
- **Attribute Pattern**: `attr="value"` -> `attr={t("key")}`

## Technical Implementation

- **Parser Configuration**: The adapter is configured to support both `.js`/`.jsx` and `.ts`/`.tsx` files by enabling the `jsx` and `typescript` Babel plugins.
- **AST Visitor**: Implementation of the Visitor pattern to efficiently navigate the tree and identify candidates for localization.
- **Generator**: Uses `@babel/generator` to reconstruct the source code from the modified AST, ensuring syntactic correctness.
npm package: @localey/svelte
Description: Svelte template adapter for Localey.
Latest version: 0.1.26

# @localey/svelte

Svelte template adapter for Localey.

The `@localey/svelte` package enables Localey to process `.svelte` files. It leverages the official Svelte compiler to parse templates and identify hardcoded strings within the Svelte syntax.

## Integration Details

The adapter integrates directly with the Svelte compiler's internal parsing engine. This ensures that it respects the nuances of Svelte's template logic, such as reactive statements and block-based flow control.

### Extraction Capabilities

- **Template Text**: Identifies static text nodes within the HTML portion of the Svelte component.
- **Element Attributes**: Detects string literals used in element attributes and component props within the template.
- **Mustache Tags**: Automatically wraps extracted strings in Svelte's mustache syntax (`{t("key")}`) for seamless integration with the Localey runtime.

## Component Architecture

- **Svelte Compiler API**: Parses the component source into a comprehensive AST.
- **Template Walker**: Navigates the Svelte-specific AST nodes (MustacheTag, Text, Attribute) to identify localization candidates.
- **Transformation Layer**: Safely performs string replacements while maintaining the integrity of the component structure.