move to docusaraus i18n standard£

Author: gingerwizard

.gitignore

@@ -2,28 +2,22 @@ node_modules
 .docusaurus
 .vercel
 build
-docs/en/development
-docs/en/engines
-docs/en/getting-started
-docs/en/interfaces
-docs/en/operations
-docs/en/sql-reference
+docs/development
+docs/engines
+docs/getting-started
+docs/interfaces
+docs/operations
+docs/sql-reference
+docs/_clients
 docs/ru
 docs/zh
-docs/ja/development
-docs/ja/engines
-docs/ja/getting-started
-docs/ja/interfaces
-docs/ja/operations
-docs/ja/sql-reference
-docs/_clients
 
 **/.DS_Store
 run.sh
 cleanup.sh
 update.sh
 
-docs/en/whats-new/changelog/_2023.md
+docs/whats-new/changelog/_2023.md
 
 .ignore
 .marksman.toml
@@ -46,11 +40,11 @@ active_links.json
 scripts/settings/tmp
 
 # Files whose content gets autogenerated
-docs/en/cloud/manage/api/invitations-api-reference.md
-docs/en/cloud/manage/api/keys-api-reference.md
-docs/en/cloud/manage/api/members-api-reference.md
-docs/en/cloud/manage/api/organizations-api-reference.md
-docs/en/cloud/manage/api/services-api-reference.md
+docs/cloud/manage/api/invitations-api-reference.md
+docs/cloud/manage/api/keys-api-reference.md
+docs/cloud/manage/api/members-api-reference.md
+docs/cloud/manage/api/organizations-api-reference.md
+docs/cloud/manage/api/services-api-reference.md
 .vscode
 .aspell.en.prepl
 *.md.bak

clickhouseapi.js

@@ -158,7 +158,7 @@ async function main() {
 
   for (const prefix in groupedEndpoints) {
     const markdownContent = generateDocusaurusMarkdown(openAPISpec, groupedEndpoints[prefix], prefix);
-    fs.writeFileSync(`docs/en/cloud/manage/api/${prefix}-api-reference.md`, markdownContent);
+    fs.writeFileSync(`docs/cloud/manage/api/${prefix}-api-reference.md`, markdownContent);
   }
 
   console.log('Markdown files generated successfully.');

contrib-writing-guide.md

@@ -193,7 +193,7 @@ Many of the pages in the docs have a section toward the top about gathering the
 
 If you are writing about some language client or visualization tool, or ELT tool and it needs to connect to an HTTPS port then this line imports the content:
 ```jsx
-import ConnectionDetails from '@site/docs/en/_snippets/_gather_your_details_http.mdx';
+import ConnectionDetails from '@site/docs/_snippets/_gather_your_details_http.mdx';
 ```
 
 and this will render it:

docs/en/_placeholders/api/_invitations-api-reference.md renamed to docs/_placeholders/api/_invitations-api-reference.md

@@ -0,0 +1,8 @@
+---
+slug: /whats-new/changelog/
+sidebar_position: 2
+sidebar_label:  2025
+title: 2025 Changelog
+note: This file is autogenerated by the yarn new-build
+---
+

docs/en/_placeholders/api/_keys-api-reference.md renamed to docs/_placeholders/api/_keys-api-reference.md

@@ -0,0 +1,43 @@
+
+<details>
+    <summary>Create GCS buckets and an HMAC key</summary>
+
+### ch_bucket_us_east1
+
+![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-bucket-1.png)
+
+### ch_bucket_us_east4
+
+![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-bucket-2.png)
+
+### Generate an Access key
+
+### Create a service account HMAC key and secret
+
+Open **Cloud Storage > Settings > Interoperability** and either choose an existing **Access key**, or **CREATE A KEY FOR A SERVICE ACCOUNT**.  This guide covers the path for creating a new key for a new service account.
+
+![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-create-a-service-account-key.png)
+
+### Add a new service account
+
+If this is a project with no existing service account, **CREATE NEW ACCOUNT**.
+
+![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-create-service-account-0.png)
+
+There are three steps to creating the service account, in the first step give the account a meaningful name, ID, and description.
+
+![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-create-service-account-a.png)
+
+In the Interoperability settings dialog the IAM role **Storage Object Admin** role is recommended; select that role in step two.
+
+![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-create-service-account-2.png)
+
+Step three is optional and not used in this guide.  You may allow users to have these privileges based on your policies.
+
+![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-create-service-account-3.png)
+
+The service account HMAC key will be displayed.  Save this information, as it will be used in the ClickHouse configuration.
+
+![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-guide-key.png)
+
+</details>

docs/en/_placeholders/api/_members-api-reference.md renamed to docs/_placeholders/api/_members-api-reference.md

@@ -0,0 +1,134 @@
+
+<details>
+  <summary>Create S3 buckets and an IAM user</summary>
+
+This article demonstrates the basics of how to configure an AWS IAM user, create an S3 bucket and configure ClickHouse to use the bucket as an S3 disk. You should work with your security team to determine the permissions to be used, and consider these as a starting point.
+
+### Create an AWS IAM user
+In this procedure, we'll be creating a service account user, not a login user.
+1.  Log into the AWS IAM Management Console.
+
+2. In "users", select **Add users**
+
+  ![create_iam_user_0](@site/docs/_snippets/images/s3/s3-1.png)
+
+3. Enter the user name and set the credential type to **Access key - Programmatic access** and select **Next: Permissions**
+
+  ![create_iam_user_1](@site/docs/_snippets/images/s3/s3-2.png)
+
+4. Do not add the user to any group; select **Next: Tags**
+
+  ![create_iam_user_2](@site/docs/_snippets/images/s3/s3-3.png)
+
+5. Unless you need to add any tags, select **Next: Review**
+
+  ![create_iam_user_3](@site/docs/_snippets/images/s3/s3-4.png)
+
+6. Select **Create User**
+
+    :::note
+    The warning message stating that the user has no permissions can be ignored; permissions will be granted on the bucket for the user in the next section
+    :::
+
+  ![create_iam_user_4](@site/docs/_snippets/images/s3/s3-5.png)
+
+7. The user is now created; click on **show** and copy the access and secret keys.
+:::note
+Save the keys somewhere else; this is the only time that the secret access key will be available.
+:::
+
+  ![create_iam_user_5](@site/docs/_snippets/images/s3/s3-6.png)
+
+8. Click close, then find the user in the users screen.
+
+  ![create_iam_user_6](@site/docs/_snippets/images/s3/s3-7.png)
+
+9. Copy the ARN (Amazon Resource Name) and save it for use when configuring the access policy for the bucket.
+
+  ![create_iam_user_7](@site/docs/_snippets/images/s3/s3-8.png)
+
+### Create an S3 bucket
+1. In the S3 bucket section, select **Create bucket**
+
+  ![create_s3_bucket_0](@site/docs/_snippets/images/s3/s3-9.png)
+
+2. Enter a bucket name, leave other options default
+:::note
+The bucket name must be unique across AWS, not just the organization, or it will emit an error.
+:::
+3. Leave `Block all Public Access` enabled; public access is not needed.
+
+  ![create_s3_bucket_2](@site/docs/_snippets/images/s3/s3-a.png)
+
+4. Select **Create Bucket** at the bottom of the page
+
+  ![create_s3_bucket_3](@site/docs/_snippets/images/s3/s3-b.png)
+
+5. Select the link, copy the ARN, and save it for use when configuring the access policy for the bucket.
+
+6. Once the bucket has been created, find the new S3 bucket in the S3 buckets list and select the link
+
+  ![create_s3_bucket_4](@site/docs/_snippets/images/s3/s3-c.png)
+
+7. Select **Create folder**
+
+  ![create_s3_bucket_5](@site/docs/_snippets/images/s3/s3-d.png)
+
+8. Enter a folder name that will be the target for the ClickHouse S3 disk and select **Create folder**
+
+  ![create_s3_bucket_6](@site/docs/_snippets/images/s3/s3-e.png)
+
+9. The folder should now be visible on the bucket list
+
+  ![create_s3_bucket_7](@site/docs/_snippets/images/s3/s3-f.png)
+
+10. Select the checkbox for the new folder and click on **Copy URL** Save the URL copied to be used in the ClickHouse storage configuration in the next section.
+
+  ![create_s3_bucket_8](@site/docs/_snippets/images/s3/s3-g.png)
+
+11. Select the **Permissions** tab and click on the **Edit** button in the **Bucket Policy** section
+
+  ![create_s3_bucket_9](@site/docs/_snippets/images/s3/s3-h.png)
+
+12. Add a bucket policy, example below:
+```json
+{
+	"Version": "2012-10-17",
+	"Id": "Policy123456",
+	"Statement": [
+		{
+			"Sid": "abc123",
+			"Effect": "Allow",
+			"Principal": {
+				"AWS": "arn:aws:iam::921234567898:user/mars-s3-user"
+			},
+			"Action": "s3:*",
+			"Resource": [
+				"arn:aws:s3:::mars-doc-test",
+				"arn:aws:s3:::mars-doc-test/*"
+			]
+		}
+	]
+}
+```
+
+```response
+|Parameter | Description | Example Value |
+|----------|-------------|----------------|
+|Version | Version of the policy interpreter, leave as-is | 2012-10-17 |
+|Sid | User-defined policy id | abc123 |
+|Effect | Whether user requests will be allowed or denied | Allow |
+|Principal | The accounts or user that will be allowed | arn:aws:iam::921234567898:user/mars-s3-user |
+|Action | What operations are allowed on the bucket| s3:*|
+|Resource | Which resources in the bucket will operations be allowed in | "arn:aws:s3:::mars-doc-test", "arn:aws:s3:::mars-doc-test/*" |
+```
+
+:::note
+You should work with your security team to determine the permissions to be used, consider these as a starting point.
+For more information on Policies and settings, refer to AWS documentation:
+https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html
+:::
+
+13. Save the policy configuration.
+
+</details>

docs/en/_placeholders/api/_organizations-api-reference.md renamed to docs/_placeholders/api/_organizations-api-reference.md

@@ -0,0 +1,13 @@
+<details>
+    <summary>Manage your IP Access List</summary>
+
+From your ClickHouse Cloud services list choose the service that you will work with and switch to **Settings**.  If the IP Access List does not contain the IP Address or range of the remote system that needs to connect to your ClickHouse Cloud service, then you can resolve the problem with **Add IPs**:
+
+![Check to see if the service allows traffic](@site/docs/_snippets/images/ip-allow-list-check-list.png)
+
+Add the individual IP Address, or the range of addresses that need to connect to your ClickHouse Cloud service. Modify the form as you see fit and then **Save**.
+
+![Add your current IP address](@site/docs/_snippets/images/ip-allow-list-add-current-ip.png)
+
+</details>
+

docs/en/_placeholders/api/_services-api-reference.md renamed to docs/_placeholders/api/_services-api-reference.md

@@ -0,0 +1,86 @@
+<br/>
+1. After creating your ClickHouse Cloud Service, on the `Connect your app` screen, select MySQL from the drop down.
+<br/>
+
+<div class="eighty-percent">
+![Credentials screen - Prompt](./images/mysql1.png)
+</div>
+
+2. Toggle the switch to enable the MySQL interface for this specific service. This will expose port `3306` for this service and prompt you with your MySQL connection screen that include your unique MySQL username. 
+
+<br/>
+<div class="eighty-percent">
+![Credentials screen - Enabled MySQL](./images/mysql2.png)
+</div>
+<br/>
+
+Alternatively, in order to enable the MySQL interface for an existing service:
+
+3. Ensure your service is in `Running` state then click on the service you want to enable the MySQL interface for. Select "Connect" from the left menu:
+
+<br/>
+<div class="eighty-percent">
+![Connection screen - Prompt MySQL](./images/mysql3.png)
+</div>
+<br/>
+
+
+4. Select MySQL from the `Connect With` drop down.
+
+<br/>
+![Connection screen - Prompt MySQL](./images/mysql4.png)
+<br/>
+
+5. Toggle the switch to enable the MySQL interface for this specific service. This will expose port `3306` for this service and prompt you with your MySQL connection screen that include your unique MySQL username. 
+
+![Connection screen -  MySQL Enabled](./images/mysql5.png)
+
+## Creating multiple MySQL users in ClickHouse Cloud
+
+By default, there is a built-in `mysql4<subdomain>` user, which uses the same password as the `default` one. The `<subdomain>` part is the first segment of your ClickHouse Cloud hostname. This format is necessary to work with the tools that implement secure connection, but don't provide [SNI information in their TLS handshake](https://www.cloudflare.com/learning/ssl/what-is-sni), which makes it impossible to do the internal routing without an extra hint in the username (MySQL console client is one of such tools).
+
+Because of this, we _highly recommend_ following the `mysql4<subdomain>_<username>` format when creating a new user intended to be used with the MySQL interface, where `<subdomain>` is a hint to identify your Cloud service, and `<username>` is an arbitrary suffix of your choice.
+
+:::tip
+For ClickHouse Cloud hostname like `foobar.us-east1.aws.clickhouse.cloud`, the `<subdomain>` part equals to `foobar`, and a custom MySQL username could look like `mysql4foobar_team1`.
+:::
+
+You can create extra users to use with the MySQL interface if, for example, you need to apply extra settings.
+
+1. Optional - create a [settings profile](/sql-reference/statements/create/settings-profile) to apply for your custom user. For example, `my_custom_profile` with an extra setting which will be applied by default when we connect with the user we create later:
+
+    ```sql
+    CREATE SETTINGS PROFILE my_custom_profile SETTINGS prefer_column_name_to_alias=1;
+    ```
+
+    `prefer_column_name_to_alias` is used just as an example, you can use other settings there.
+2. [Create a user](/sql-reference/statements/create/user) using the following format: `mysql4<subdomain>_<username>` ([see above](#creating-multiple-mysql-users-in-clickhouse-cloud)). The password must be in double SHA1 format. For example:
+
+    ```sql
+    CREATE USER mysql4foobar_team1 IDENTIFIED WITH double_sha1_password BY 'YourPassword42$';
+    ```
+
+    or if you want to use a custom profile for this user:
+
+    ```sql
+    CREATE USER mysql4foobar_team1 IDENTIFIED WITH double_sha1_password BY 'YourPassword42$' SETTINGS PROFILE 'my_custom_profile';
+    ```
+
+    where `my_custom_profile` is the name of the profile you created earlier.
+3. [Grant](/sql-reference/statements/grant) the new user the necessary permissions to interact with the desired tables or databases. For example, if you want to grant access to `system.query_log` only:
+
+    ```sql
+    GRANT SELECT ON system.query_log TO mysql4foobar_team1;
+    ```
+
+4. Use the created user to connect to your ClickHouse Cloud service with the MySQL interface.
+
+### Troubleshooting multiple MySQL users in ClickHouse Cloud
+
+If you created a new MySQL user, and you see the following error while connecting via MySQL CLI client:
+
+```
+ERROR 2013 (HY000): Lost connection to MySQL server at 'reading authorization packet', system error: 54
+```
+
+In this case, ensure that the username follows the `mysql4<subdomain>_<username>` format, as described ([above](#creating-multiple-mysql-users-in-clickhouse-cloud)).