doc: translate documentation

docs/docs/en/ballance-properties.md

@@ -1,4 +1,29 @@
 # Ballance Properties
 
-!!! info "Work in Progress"
-    This part of manual still work in progress.
+The Ballance attributes are distinct from the Virtools attributes, which are a set of attributes dedicated to Ballance mapping. These properties are hosted in the scene and do not change within the same scene (mapping does not involve scene switching in Blender). The panels related to the Ballance property can be found in the `Scene` properties panel, as shown below, and they are:
+
+* `Ballance Elements` panel (red arrows), corresponding to Ballance elements
+* `BME Materials` panel (green arrow), corresponds to BME materials.
+* `Ballance Map` panel (blue arrow), which corresponds to the Ballance map information.
+
+Among these, only the Ballance Map information is the one you need to focus on, the other attributes are not normally of interest, except in the case of errors in some of the materials or meshes in the map.
+
+![](../imgs/ballance-properties.png)
+
+## Ballance Map Information
+
+Ballance Map infomation currently has only one option, Sector (map sector count). This attribute indicates the final desired number of sectors for the current map. This attribute is mainly used to work around the bug of exporting map, see the [Import and Export Virtools Document](./import-export-virtools.md) section for details on the bug.
+
+The only thing you need to do is to check if this field is the number of sectors you expect before exporting the final map. Note that although you can set this field at the beginning of creating your map, there are other features in BBP that may modify this field, such as adding elements, importing Virtools documents, etc. For example, if you have a map with sector 3 specified and you are adding an element that belongs to sector 4, this value will automatically increase to 4. Similarly, when importing a Ballance map with a total of 4 sectors, this value will also increase to 4 (if the previous value was less than 4). The main reason for doing this is so that users can use this plugin without perceiving this value, especially when making slight modifications to some existing maps. Doing so, however, may not meet the user's needs in some cases, so it is still recommended that you check this field before exporting.
+
+## Ballance Elements
+
+Ballance Elements keep a record of the meshes of all the elements you have added using the BBP Add Elements feature. Meshes generally take up the largest amount of data in a 3D file, so reducing the number of meshes, i.e. by sharing meshes between objects of the same shape, can drastically reduce the size of the map file. When you use BBP to add an element-related function, it will first try to get the element's mesh from here, and if there is no corresponding mesh, it will be loaded and recorded here.
+
+This panel is for viewing only, not editing. If you have accidentally modified the meshes of a BBP-added element (which should not have been modified in the first place) and want to restore its original shape, just click `Reset Ballance Elements` to reset all the element meshes in the list to their correct state.
+
+## BME Materials
+
+Similar to the Ballance Elements, records the materials used when adding floor using BME. This is also designed so that materials can be reused, so that you don't need to create a set of materials associated with each object you create, greatly reducing the number of duplicate materials.
+
+This panel is for viewing only, not editing. When you accidentally modify BME related materials (which should not have been modified) and want to restore them, just click `Reset BME Materials` to reset all materials in the list to their correct state.

docs/docs/en/import-export-virtools.md

@@ -1,4 +1,55 @@
 # Import and Export Virtools Document
 
-!!! info "Work in Progress"
-    This part of manual still work in progress.
+!!! warning "This is experimental content"
+    Native importing and exporting of Virtools documents is experimental content for the BBP plugin, it may have many problems, see the [Report Issue](./report-bugs.md) section to learn more. When problems are encountered, please report them. the authors of the BBP plugin are not responsible for any consequences resulting from problems with the BBP plugin.
+
+## Import Virtools File
+
+Virtools files can be imported by clicking `File - Import - Virtools File`. Importing supports CMO, VMO and NMO files. Clicking on it will bring up the file opening window and show the import settings in the sidebar. First of all, you need to select the Virtools file to be imported, and then configure the import settings in the sidebar. After configuring the import settings, you can click Import to start the import, and wait for the status bar at the bottom of Blender to indicate that the import is complete.
+
+### Conflict Options
+
+The Conflict Options section indicates what to do when the importer encounters duplicate object names. There are 4 levels, for Object, Mesh, Material and Texture. There are 2 ways to handle it: Rename and Use Current. When Rename is selected and a duplicate name is encountered, a suffix will be added to the name to make it unique. By choosing Use Current, the import of the item from the file will be ignored and the item with the same name will be used instead, which already exists in the Blender document.
+
+!!! info "Differences from Virtools conflict resolution"
+    Compared to the conflict resolution dialog in Virtools, the conflict resolution options provided by the BBP plugin do not support replacement, and the granularity is not fine-tuned to individual instances, but only for an entire type. So you can't set a different conflict resolution for each instance of a conflict individually. However, this setting is sufficient for most scenarios.
+
+The default values for the options in the Conflict Options section are the solutions that are usually selected for import. Of course, special settings are needed for special import situations, e.g. if you are importing an externally exported element model from the original version, you may be able to use Use Current option in material options instead of making a copy. The correct use of the conflict options is a matter of mapping experience and is not taught in this manual.
+
+### Virtools Params
+
+It is well known that Virtools uses a system-based multi-byte character encoding to process documents, and is therefore prone to what is known as garbling; Blender itself does not suffer from garbling, however, if we do not read a Virtools document with the correct encoding, the characters stored in it may still appear garbled when the Virtools document is imported into Blender. The Encodings property in the Virtools Params section specifies the encodings for reading Virtools documents. Multiple encodings can be specified, separated by a `;` (semicolon). Some common encodings are listed below:
+
+* 1252 (Windows only): Western European encoding used by Ballance.
+* 936 (Windows only): the default encoding for Chinese Windows system.
+* CP1252 (non-Windows): Western European encoding used by Ballance.
+* CP936 (non-Windows): the default encoding for Chinese Windows system.
+
+The encoding attribute is very important, if you set the wrong encoding, the names of the various objects imported into Blender will be unrecognizable.
+
+!!! warning "Encoding is a platform dependent setting"
+    According to the implementation of LibCmo, the underlying library used by BBP's Virtools documentation for the import module, the encoding attribute is a platform dependent setting. Under Windows, the [Windows Code Page](https://learn.microsoft.com/en-us/windows/win32/intl/code-page-identifiers) number is required here. Under other operating systems, LibCmo uses iconv for character encoding and decoding, so you need to use the legal [Iconv Encoding Identifier](https://www.gnu.org/software/libiconv/).
+
+## Export Virtools File
+
+Virtools files can be exported by clicking `File - Export - Virtools File`. Clicking on it will bring up the file opening window and show you the export settings in the sidebar. First of all, you need to select the location of the exported Virtools file, then configure the export settings in the sidebar, after configuring the export settings, you can click Export to start the export, and wait for the status bar at the bottom of Blender to indicate that the export is complete.
+
+### Export Target
+
+The Export Target section is used to determine which objects you need to export to a Virtools document. You can choose to export a collection or an object and select the corresponding collection or object below. Note that selecting a collection will export the objects in the internal collection as well, i.e. exporting nested collections is supported.
+
+### Virtools Params
+
+The Virtools Params section is similar to the one in the importing Virtools document; the Encodings property determines the encoding used when exporting a Virtools document.
+
+The Global Texture Save Option determines how textures that are set to Use Global are actually saved. In general, setting it to Raw Data will 100% guarantee that the saved Virtools document will contain the correct texture, but it may be larger, while setting it to External will minimize the size of the file, but there may be problems with the exported document not finding the texture file. We recommend that you specify how each material should be saved individually when you set it up, rather than relying on the global option to set it up. This option is for re-editing old maps that rely on the Global Texture Saving Option. It should also be noted that even though there is a Use Global option in this option, please **don't** select it or it will result in an error, because obviously you can't have a global option that then uses the global option's settings.
+
+The Use Compress property specifies whether saved documents are stored compressed. Compression can significantly reduce the size of a document, and on modern computer platforms, the performance loss caused by compression is almost negligible. When Use Compress is selected, an additional Compress Level attribute is displayed, which specifies the level of compression; the higher the value, the greater the compression rate and the smaller the file.
+
+### Ballance Params
+
+The Ballance Params section contains parameters that optimize the export process for Ballance-specific content.
+
+Successive Sector is an option to work around a bug that occurs when exporting groups of sectors. For some reason, if there are no elements in a sector (actually, no objects are grouped in a sector group), the export plugin thinks that the sector group doesn't exist and misses the export. And since Ballance determines the final sector, i.e. the sector where the spaceships appears, by incrementing the number of sectors from 1 to the last sector group that exists, the combination of the two causes Ballance to incorrectly determine the number of sectors in the map, and thus display the spaceships in the wrong sector, which is an export bug. when this option is checked, the exported document will be pre-defined according to the number of sectors specified in the Ballance Map information in the current Blender file. When this option is checked, the exported document will pre-create all of the sectors according to the number of sectors specified in the Ballance map information in the current Blender file before exporting, so that you don't miss creating some sector groups, and the spaceships will be displayed in the correct sectors.
+
+This option is usually checked when exporting playable maps, if you just want to export some models then you need to turn this option off, otherwise it will create a lot of useless sector groups in the final file.

docs/docs/en/index.md

@@ -1,6 +1,6 @@
 # Ballance Blender Plugin User Manual
 
-!!! info "May Outdated"
+!!! info "May be Outdated"
     This document is translated from other languages and may not always be up to date.
 
 Welcome to the Ballance Blender Plugin, the user manual for the free and open source Ballance map creation suite.

docs/docs/zh-cn/ballance-properties.md

@@ -1,6 +1,6 @@
 # Ballance属性
 
-Ballance属性有别于Virtools属性，它是专门为Ballance制图服务的一系列属性。这些属性寄宿于场景，在同一场景中（制图不会涉及Blender中的场景切换），这些属性不会改变。在`Scene`属性面板可以找到Ballance属性相关的面板，如下图所示，分别是：
+Ballance属性有别于Virtools属性，它是专门为Ballance制图服务的一系列属性。这些属性寄宿于场景，在同一场景中（制图不会涉及Blender中的场景切换），这些属性不会改变。在`Scene`属性面板可以找到Ballance属性相关的面板，如下图所示，它们分别是：
 
 * `Ballance Elements`面板（红色箭头），对应Ballance机关
 * `BME Materials`面板（绿色箭头），对应BME材质
@@ -12,9 +12,9 @@ Ballance属性有别于Virtools属性，它是专门为Ballance制图服务的
 
 ## Ballance地图信息
 
-Ballance地图信息目前只有一个选项，Sector（地图小节数）。此属性指示了当前地图的最终期望小节数。这个属性主要是用于解决导出地图Bug的，具体Bug内容可参考导入导出Virtools文档章节。
+Ballance地图信息目前只有一个选项，Sector（地图小节数）。此属性指示了当前地图的最终期望小节数。这个属性主要是用于解决导出地图Bug的，具体Bug内容可参考[导入导出Virtools文档](./import-export-virtools.md)章节。
 
-你需要做的唯一一件事就是在导出最终地图前检查此字段是否是你期望的小节数。需要注意的是，尽管你可以在创建地图的一开始就设置此字段，然而BBP中的其它一些功能可能会修改此字段，比如：添加机关，导入Virtools文档等。例如当你的地图小节指定为3，你正在添加一个归属于第4小节的机关，那么此值会自动增加到4。同理，在导入一个总共4小节的Ballance地图时，此值也会增加到4（如果先前值小于4的话）。这主要是为了用户可以在没有感知到此值的情况下使用此插件，尤其是在对某些现有地图进行略微修改时。然而如此操作，可能会在某些情况下不能满足用户的需求，所以仍建议你在导出前检查此字段。
+你需要做的唯一一件事就是在导出最终地图前检查此字段是否是你期望的小节数。需要注意的是，尽管你可以在创建地图的一开始就设置此字段，然而BBP中的其它一些功能可能会修改此字段，比如：添加机关，导入Virtools文档等。例如当你的地图小节指定为3，你正在添加一个归属于第4小节的机关，那么此值会自动增加到4。同理，在导入一个总共4小节的Ballance地图时，此值也会增加到4（如果先前值小于4的话）。这么做主要是为了用户可以在没有感知到此值的情况下使用此插件，尤其是在对某些现有地图进行略微修改时。然而如此操作，可能会在某些情况下不能满足用户的需求，所以仍建议你在导出前检查此字段。
 
 ## Ballance机关
 

docs/docs/zh-cn/import-export-virtools.md

@@ -25,7 +25,7 @@ Conflict Options（冲突解决选项）章节指示了当导入器遇到物体
 * CP1252（非Windows下）：Ballance所用的西欧编码
 * CP936（非Windows下）：中文默认编码
 
-编码属性非常重要，如果设置了错误的编码，导入Blender的各类物体的名称会出现不可认知的情况
+编码属性非常重要，如果设置了错误的编码，导入Blender的各类物体的名称会出现不可认知的情况。
 
 !!! warning "编码是一个平台相关的设定"
     根据BBP的Virtools文档导入模块使用的底层库LibCmo的实现，编码属性是一个平台相关的设定。在Windows下，这里需要填写的是[Windows代码页](https://learn.microsoft.com/en-us/windows/win32/intl/code-page-identifiers)数字。而在其它操作系统下，LibCmo使用iconv进行字符编码解码，因此需要使用合法的[iconv编码标识符](https://www.gnu.org/software/libiconv/)。