Skip to content

Latest commit

 

History

History
241 lines (157 loc) · 9.19 KB

CONTRIBUTING.md

File metadata and controls

241 lines (157 loc) · 9.19 KB
Raw

Vue I18n Contributing Guide

General Guidelines

Thanks for understanding that English is used as a shared language in this repository. Maintainers do not use machine translation to avoid miscommunication due to error in translation. If description of issue / PR are written in non-English languages, those may be closed.

It is of course fine to use non-English language, when you open a PR to translate documents and communicates with other users in same language.

Pull Request Guidelines

  • The master branch is the latest stable version release. All development should be done in dedicated branches.

  • Checkout a topic branch from the relevant branch, e.g. master, and merge back against that branch.

  • Work in the src folder and DO NOT checkin dist in the commits.

  • If adding new feature:

    • Add accompanying test case.
    • Provide convincing reason to add this feature. Ideally you should open a suggestion issue first and have it greenlighted before working on it.

  • If fixing a bug:

    • Provide detailed description of the bug in the PR. Live demo preferred.
    • Add appropriate test coverage if applicable.

  • It's OK to have multiple small commits as you work on the PR - we will let GitHub automatically squash it before merging.

  • Make sure npm test passes. (see development setup)

Work Step Example

  • Fork the repository from intlify/vue-i18n !
  • Create your topic branch from master: git branch my-new-topic origin/master
  • Add codes and pass tests !
  • Commit your changes: git commit -am 'Add some topic'
  • Push to the branch: git push origin my-new-topic
  • Submit a pull request to master branch of intlify/vue-i18n repository !

Development Setup

You will need Node.js version 16+, and PNPM.

We also recommend installing ni to help switching between repos using different package managers. ni also provides the handy nr command which running npm scripts easier.

After cloning the repo, run:

$ pnpm i # install the dependencies of the project

A high level overview of tools used:

Scripts

pnpm build

The build script builds all public packages (packages without private: true in their package.json).

Packages to build can be specified with fuzzy matching:

# build message-compiler only
pnpm build -- message-compiler

# build all packages
pnpm build -- --all

Build Formats

By default, each package will be built in multiple distribution formats as specified in the buildOptions.formats field in its package.json. These can be overwritten via the -f flag. The following formats are supported:

  • global

    • For direct use via <script> in the browser.
    • Note: global builds are not UMD builds. Instead they are built as IIFEs.

  • esm-bundler

    • Leaves prod/dev branches with process.env.NODE_ENV guards (to be replaced by bundler)
    • Does not ship a minified build (to be done together with the rest of the code after bundling)
    • For use with bundlers like webpack, rollup and parcel.

  • esm-browser

    • For usage via native ES modules imports (in browser via <script type="module">, or via Node.js native ES modules support in the future)
    • Inlines all dependencies - i.e. it's a single ES module with no imports from other files
      • This means you must import everything from this file and this file only to ensure you are getting the same instance of code.
    • Hard-coded prod/dev branches, and the prod build is pre-minified (you will have to use different paths/aliases for dev/prod)

  • cjs

    • For use in Node.js server-side rendering via require().
    • The dev/prod files are pre-built, but are dynamically required based on process.env.NODE_ENV in index.js, which is the default entry when you do require('vue-i18n').

For example, to build compiler with the global build only:

pnpm build -- message-compiler -f global

Multiple formats can be specified as a comma-separated list:

pnpm build -- message-compiler -f esm-browser,cjs

Build with Source Maps

Use the --sourcemap or -s flag to build with source maps. Note this will make the build much slower.

Build with Type Declarations

The --types or -t flag will generate type declarations during the build and in addition:

  • Roll the declarations into a single .d.ts file for each package;
  • Generate an API report in <projectRoot>/temp/<packageName>.api.md. This report contains potential warnings emitted by api-extractor.
  • Generate an API model json in <projectRoot>/temp/<packageName>.api.json. This file can be used to generate a Markdown version of the exported APIs.

pnpm dev

The dev script bundles a target package (default: vue-i18n) in a specified format (default: global) in dev mode and watches for changes. This is useful when you want to load up a build in an HTML page for quick debugging:

$ pnpm dev

> rollup v1.19.4
> bundles packages/vue-i18n/src/index.ts → packages/vue-i18n/dist/vue-i18n.global.js...

  • The dev script also supports fuzzy match for the target package, but will only match the first package matched.

  • The dev script supports specifying build format via the -f flag just like the build script.

  • The dev script also supports the -s flag for generating source maps, but it will make rebuilds slower.

pnpm test

The test script simply calls the jest binary, so all Jest CLI Options can be used. Some examples:

# run all tests
$ pnpm test

# run tests in watch mode
$ pnpm test -- --watch

# run all tests under the runtime-core package
$ pnpm test -- compiler

# run tests in a specific file
$ pnpm test -- fileName

# run a specific test in a specific file
$ pnpm test -- fileName -t 'test name'

Project Structure

This repository employs a monorepo setup which hosts a number of associated packages under the packages directory:

flowchart TD
  message-compiler
  core-base
  core
  vue-i18n-core
  petite-vue-i18n
  vue-i18n

  subgraph Framework Agnostice Packages
    core-base --> message-compiler
    core --> core-base
  end

  subgraph Vue Layer Packages
    vue-i18n-core --> core-base
    vue-i18n --> core-base
    vue-i18n --> vue-i18n-core
    petite-vue-i18n --> core-base
    petite-vue-i18n --> vue-i18n-core
  end
Loading
  • message-compiler: The intlify message format compiler.
  • core-base: The inlitfy core logic implementation.
  • core: The intlify core "full build" which includes both the runtime AND the compiler.
  • vue-i18n-core: The vue-i18n core implementation.
  • petite-vue-i18n: The vue-i18n "small build" which includes both the runtime AND the compiler.
  • vue-i18n: The vue-i18n "full build" which includes both the runtime AND the compiler.

There are some caveats to these packages:

  • The modules vue-i18n and vue-i18n-core, the core logic of petite-vue-i18n, should be imported with relative paths.
  • Similarly for core, modules of core-base, which is the core logic implemented, should be imported with relative paths.

Importing Packages

The packages can import each other directly using their package names. Note that when importing a package, the name listed in its package.json should be used. Most of the time the @intlify/ prefix is needed:

import { baseCompile } from '@intlify/compiler'

This is made possible via several configurations:

  • For TypeScript, compilerOptions.path in tsconfig.json
  • For plain Node.js, they are linked using PNPM Workspaces.

Contributing Tests

Unit tests are collocated with directories named test. Consult the Jest docs and existing test cases for how to write new test specs. Here are some additional guidelines:

Use the minimal API needed for a test case. For example, if a test can be written without involving the reactivity system ra component, it should be written so. This limits the test's exposure to changes in unrelated parts and makes it more stable.

Financial Contribution

As a pure community-driven project without major corporate backing, we also welcome financial contributions via GitHub Sponsors and Patreon

Funds donated via GitHub Sponsors and Patreon go to support kazuya kawaguchi full-time work on Intlify.

Credits

Thank you to all the people who have already contributed to Intlify project and my OSS work !