Install & Deploy

Configuration Token

i18n.site incorporates a built-in i18 translation tool. Please click here to refer to the i18 documentation to configure the access token.

Install

bash <(curl -sS https://i.i18n.site) i18n.site

Demo Project

Let's commence with a demo project to learn how to utilize i18n.site.

We initially clone the demo repository and execute the command as follows:

git clone https://github.com/i18n-site/demo.i18n.site.git md
git clone https://github.com/i18n-site/demo.i18n.site.docker.git docker

Users in mainland China can:

git clone https://atomgit.com/i18n/demo.i18n.site.git md
git clone https://atomgit.com/i18n/demo.i18n.site.docker.git docker

The directory name for the demo.i18n.site code base clone must be md to facilitate local preview with docker.

Translate

Firstly, enter the md directory and run i18n.site, which will translate en to zh.

After running, translation and cache files will be generated. Please remember to add git add. to the repository in the md directory.

Local Preview

Install and initiate docker ( MAC users are recommended to use orbstack as the runtime for docker).

Then, enter the docker directory and run ./up.sh, and afterwards visit https://127.0.0.1 for local preview.

Post Content

i18n.site adopts a single-page application architecture, and the website entrance page and website content are independently deployed.

After conducting the above translation, directories htm and v will be generated under the md/out/dev directory.

Here, dev indicates that it is constructed based on the .i18n/htm/dev.yml configuration file.

dev directory:

The htm directory is the website entrance page.

The v directory contains website content with version numbers.

Local preview does not concern about the version number and will copy all files to the out/dev/v/0.1.0 directory.

For official release, changed files will be copied to the new version number directory.

Use -c to Specify the Configuration File

Different configuration files will create corresponding directories in the out directory.

For example, .i18n/htm/ol.yml will create the out/ol directory.

dev.yml and ol.yml are the default configurations.

dev is the abbreviation of development, denoting the development environment, used for local preview, and is also the default configuration file. ol is the abbreviation of online, indicating the online environment, which is used for official release. It is also the default configuration file when using the command line parameters -n to npm for release.

You can also create other configuration files. Use --htm_conf on the command line to specify the configuration file name to be used:

for example:

i18n.site --htm_conf yourConfig --save

Here --save represents the updated release version number.

Publish content to npmjs.com

Publishing content to npmjs.com is the recommended default solution (see Front-end High Availability).

npm login & Release

Install nodejs and log in with npm login.

Edit md/.i18n/htm/ol.yml and modify i18n.site in v: //unpkg.com/i18n.site to your own npm package name.

Just use the unoccupied package name on npmjs.com. Utilizing the website domain name as the package name is a good choice.

When publishing based on the npm package, be sure to use //unpkg.com/ for the prefix of the v: value. i18n.site has specially optimized the cache time of /.v under this prefix path to achieve timely viewing of new releases.

Run i18n.site --npm or i18n.site -n in the md directory to translate and publish.

If you use a continuous integration environment to publish, there is no need to install nodejs. Just copy the logged-in and publishing permission ~/.npmrc to the environment.

If you modify the package name of v: in ol.yml, please be sure to delete .i18n/v/ol first and then publish it.

Proxy Server for npm Publication

If users in mainland China encounter network issues and are unable to publish npm packages, they can set the environment variable https_proxy to configure the proxy server.

Assuming that your proxy server port is 7890, you can write:

https_proxy=http://127.0.0.1:7890 i18n.site -n

Self-Hosted Content

If you want to self-host the content, first edit md/.i18n/htm/ol.yml and change v: //unpkg.com/i18n.site to your URL prefix, such as v: //i18n-v.xxx.com.

Enter the md directory and run

i18n.site --htm_conf ol --save

or abbreviation

i18n.site -c ol -s

Then, configure the content in the md/out/ol/v directory to the URL prefix path set in v:.

Finally, configure the cache time of the path ending in /.v to 1s; otherwise, the newly released content cannot be accessed immediately.

The cache time for other paths can be set to one year or more to reduce unnecessary requests.

Host Content to s3

To self-host content, in addition to using your own server, another common option is to use S3 + CDN.

You can utilize rclone to log in to the S3 server, and then refer to and modify the subsequent script. For each release, only copy the incremental changes to S3.

i18n.site -c ol -s
s3=your-s3
bucket=your-bucket
ver=$(head -1 .i18n/v/ol/v.hash | cut -c 2-)
rclone copy --overwrite-dir out/ol/htm/v/$ver $s3:/$bucket/$ver
rclone copy out/ol/v/.v "$s3:/$bucket/"

Remember to configure CDN such that the cache time for the path ending with /.v is 1s, otherwise, the newly released content cannot be accessed promptly.

Publish the Website

The website can be deployed anywhere, and both github page and cloudflare page are excellent choices.

As the website adopts a single-page application architecture, it is necessary to remember to rewrite the URL paths that do not contain . to index.html.

The website entry page only needs to be deployed once, and there is no need to redeploy the website entry page for subsequent content updates.

Deploy on github page

Firstly, click here to create an organization on github. Hereinafter, the organization name is taken as i18n-demo as an example.

Then create the repository i18n-demo.github.io under this organization (please replace i18n-demo with the organization name you created):

When publishing the content in the previous section, out/ol/htm has already been generated. Please enter this directory and execute:

ln -s index.html 404.html

Because github page does not support URL path rewriting, 404.html is used instead.

Then run the following command in the htm directory (remember to replace i18n-demo/i18n-demo.github.io.git with your own repository address):

git init
git branch -M main
git remote add origin [email protected]:i18n-demo/i18n-demo.github.io.git
git push -u origin main -f

After pushing the code, wait for the successful operation of the deployment of github page (as shown in the figure below) before being able to access.

For the demo page, please refer to:

https://i18n-demo.github.io

Deploy on cloudflare page

cloudflare page compared to github page, it provides path rewriting and is more friendly and accessible to mainland China. It is highly recommended.

The deployment of cloudflare page is usually based on the above deployment of github page.

Create a project and bind the above-mentioned i18n-demo.github.io repository.

The process is shown in the figure below:

Please click Add Account to authorize access to the i18n-demo organization.

If you have bound the repository of another organization before, you may need to click Add Account twice to authorize twice before the new organization is displayed.

Next, select the repository i18n-demo.github.io, then click Begin setup, and use the default values for the subsequent steps.

After the first binding, you need to wait for a few minutes before being able to access.

After deployment, you can bind a custom domain name.

After binding the custom domain name, please go to the domain name to configure the path rewriting of the single-page application, as shown below:

The rules in the above picture are as follows. Please replace i18n.site in the first line below with the domain name you bound.

(http.host in {"i18n.site"}) and not (
substring(http.request.uri.path,-3) in {".js" ".gz"} or
substring(http.request.uri.path,-4) in {".htm" ".rss" ".css" ".svg" ".ico" ".png" ".xml" ".txt"} or
substring(http.request.uri.path,-5) in {".html" ".avif" ".json"} or
ends_with(http.request.uri.path,".webmanifest")
)

In addition, please configure the cache rules, as shown below, and set the cache duration to one month.

Please change the domain name matching in the second step in the picture above to the domain name you bound.

Optimization of Website Deployment in Mainland China

If you want to obtain better accessibility performance in the network environment of mainland China, please register a domain name first.

Then, use the object storage of the cloud vendors in mainland China + CDN to deploy the following content of out/ol/htm.

You can use edge computing to rewrite the path to adapt to single-page applications. For example, Baidu Smart Cloud CDN can be configured like this:

var uri=r.uri,p=uri.lastIndexOf('.');
if(
  p<0 || !'|avif|css|html|ico|js|json|png|svg|txt|webmanifest|xml|'.includes('|'+uri.slice(p+1)+'|')
){
  r.uri='/index.html'
}
r.respHeader(()=>{
var t = [];
r.rawHeadersOut.forEach((i)=>{
    var out = r.headersOut;
    var key = i[0].toLowerCase();
    if(key.startsWith('x-')||key.startsWith('ohc-')){
        delete out[key]
    }
    out['Cache-Control']='max-age='+9e5;
    ['Content-MD5','Age','Expires','Last-Modified'].forEach((i)=>delete out[i])
})
})

Because the MX record and the CNAME record cannot coexist, if you want to receive domain name mails at the same time, you need to cooperate with the cname_flatten script to flatten the CNAME to the A record.

In addition, because the overseas traffic charges of the cloud vendors in mainland China are relatively expensive, if you want to optimize the cost, you can use Huawei Cloud DNS's free geographical resolution and Cloudflare for SaaS's custom domain name (as shown below) to achieve traffic diversion ── the traffic in mainland China goes to Baidu Cloud CDN, and the international traffic goes to cloudflare.

These deployment optimization solutions are more complex and will be introduced in separate chapters in the future.

Generic Domain Name Redirection

If you use i18n.site to generate a website as your main website, you usually need to configure pan-domain redirection, that is, redirect the access of *.xxx.com (including www.xxx.com) to xxx.com.

This requirement can be achieved with the help of Alibaba Cloud CDN EdgeScript ( English document / Chinese document )

Add the domain name in Alibaba Cloud CDN and point the *.xxx.com domain name to the CNAME in Alibaba Cloud CDN.

For example, the pan-domain name redirection configuration of *.i18n.site in the picture above is as follows:

rewrite(concat('https://i18n.site/',$uri), 'redirect',301)

Deploy with nginx

Please add a configuration similar to the following in the server paragraph of nginx. Please change /root/i18n/md/out/ol/htm to the path of your own project out/ol/htm :

location / {
  root  /root/i18n/md/out/ol/htm;
  add_header Cache-Control "max-age=9999999";
  if ($uri !~* \.(avif|css|html|ico|js|json|png|svg|txt|webmanifest|xml)$) {
     rewrite ^ /index.html last;
  }
}

Directory Structure

public

Static files of the website, such as favicon.ico, robots.txt, and so on.

The icon files here can be generated by using realfavicongenerator.net.

.i18n

Under the .i18n directory are the configuration files, translation cache, etc. of i18n.site. For details, see the next chapter "Configuration".

en

Source language directory, corresponding to the en value within the fromTo key in the .i18n/conf.yml configuration file

i18n:
  fromTo:
    en: zh

Please refer to i18 for the configuration of translation.