auto-localization/README.md

A powerful tool to automatically extract text strings from React Native (or React) components and generate localization files. Supports generating JSON or JavaScript/TypeScript constants files for easy integration with your app's localization system.

# auto-localization

auto-localization is a tool to automatically extract hardcoded text strings from React/React Native components and generate localization files in either JSON or JavaScript/TypeScript constants format. It simplifies the process of managing localization in your project, making it easy to integrate new languages into your app without manually finding and translating strings.

## Features

- **Automatic String Extraction**:  
  Extracts text strings from React Native or React components written in JavaScript or TypeScript.

- **Flexible Output Formats**:

  - Generate JSON localization files for use with localization libraries.
  - Generate JavaScript/TypeScript constants for integrating localized strings as constants in your codebase.

- **Merge with Existing Files**:  
  New strings are automatically merged with any existing localization data in your target files, avoiding accidental overwrites.

- **Customizable Key Formatting**:  
  Supports camelCase or snake_case formatting for generated keys, making it easy to follow code conventions.

- **Support for JSX and TSX**:  
  Works with both JSX (React) and TSX (React Native) syntax.

## Installation
 To install `auto-localization`, use the following command:
 
```bash
npm install auto-localization
```

### Globally

To install auto-localization globally, run the following command:

```bash
npm install -g auto-localization
```

## Usage

- Extract Strings and Generate JSON Localization File

### You can extract text strings from your components and generate a JSON localization file:

```bash
npx auto-localization ./src/components/MyComponent.tsx ./src/locales/en.json
```

- This will extract strings from the specified TypeScript file (MyComponent.tsx) and generate or update the en.json file inside the src/locales directory.

### Generate JavaScript/TypeScript Constants File

- Alternatively, you can generate a JavaScript/TypeScript constants file:

```bash
npx auto-localization ./src/components/MyComponent.tsx ./src/locales/constants.ts
```

- This will generate or update the constants.ts file, which will contain all the extracted strings as constants.

## Example

```js
- Input File (MyComponent.tsx)
import React from 'react';
import { Text } from 'react-native';

const MyComponent = () => {
  const message = 'Welcome to the app!';

  return <Text>{message}</Text>;
};

export default MyComponent;

- JSON Output (en.json)
{
  "welcome_to_the_app": "Welcome to the app!"
}
- TypeScript Constants Output (constants.ts)
export const WELCOME_TO_THE_APP = "Welcome to the app!";
```

### Configuration Options

- Custom Key Formatting
- You can choose between different key formats for the extracted strings. By default, auto-localization generates keys in snake_case.

- camelCase: Converts the string into camelCase format.
- snake_case: Converts the string into snake_case format.
- You can specify the format during execution (depending on how the tool is configured in your project).

- Merge Existing Localization Data
- If the localization file already exists, auto-localization will merge new strings with the existing ones, preventing accidental overwrites of translations.

- For example, if en.json already contains:

{
"existing_key": "Existing Value"
}

- And a new string "Welcome to the app!" is extracted, the updated en.json will contain:

{
"existing_key": "Existing Value",
"welcome_to_the_app": "Welcome to the app!"
}

- Example Command with Merging

```bash
npx auto-localization ./src/components/MyComponent.tsx ./src/locales/en.json
```

## Contributing

- If you'd like to contribute to the project, feel free to open an issue or submit a pull request. Contributions are welcome!

- Steps to Contribute:
- Fork this repository.
- Create a branch with your changes.
- Open a pull request with a clear description of the changes.
- Test your changes to ensure they work as expected.

### License

This project is licensed under the MIT License.

### Acknowledgements

auto-localization uses Babel Parser for AST generation and string extraction.
Thanks to the React Native and React communities for creating amazing tools!