请问是否可以用于为第三方类库增加本地化的智能提醒注释？

[ElderJames]

你好，我的项目希望实现中英双语的注释智能提醒，这是当时的讨论，但是发布的nuget包默认会显示所有注释的内容，请问如何才能创建本地化的注释提醒呢？

[stratosblue]

@ElderJames

这个工具暂时没有为第三方库做本地化的功能，本地化信息全是从 https://learn.microsoft.com/zh-cn/dotnet 爬取的，如果要做第三方库的本地化功能需要接入翻译，暂时没时间做这个。。。

本地化注释是一项IDE支持的功能，IDE会自动根据当前的区域信息在 dll 的 xml 文件的目录下搜索对应区域名称的目录，然后加载其中的同名 xml 。

你可以在打包nuget包时将区域化的 xml 打包到对应的目录下即可。

issue中提及的方案感觉是可行的，不过要在写代码的时候手动写多语注释，然后在pack的时候将其拆分到对应的区域文件夹打包进nuget包，我看了下代码里面好像没写多语注释？如果写了的话我或许可以尝试一下这个打包逻辑。

[ElderJames]

感谢答复，目前确实没多少注释，但接下来因为要发正式版了，将会逐步完善公开API的注释。xml可以在代码中写英文的，我们后面再用工具翻译生成的xml就行。 另外我找到了nuget官方文档，里面确实有一个利用Resource的打包方式，发布语言包。 https://github.com/NuGet/Samples/tree/main/Satellite-Packages 这应该就跟本项目的打包逻辑一致了。只是从注释到打包的过程，我们对这方面知识比较匮乏，所以如果可以的话，请帮助我们实现这个打包逻辑，能实现的话对我们项目的帮助将会非常大。

再次感谢！

[stratosblue]

@ElderJames 看了一下，示例打包是有资源文件需要分包打包才那样做的，如果仅仅是智能感知文件的话我觉得可以不那么做。

如果仅仅是静态的本地化xml打包的话还是很简单的。不过机翻的效果感觉可能还是差点意思。issue中提到的直接在注释中多语言注释感觉有点意思，除了注释可能比较长。。

试了下写了个demo，包含静态本地化xml和多语言注释的混合打包，你看下能用吗

MultiLanguageIntellisensePackageTest.zip

[ElderJames]

这个方法真的可以！十分感激！

我觉得完善下可以做成一个单独的msbuild项目了

[ElderJames]

这个方法适合支持少量语言的情况，因为注释中写多语言的注释其实不是很重要。所以最好可以实现指定一个目录专门放置xml文件，不同的语言用不同的文件名，然后在打包时放到对应目录中。这样对翻译和维护工作就更加方便了。只是这又要考虑增量修改的问题，如何做到已翻译过的不被改变，也是一个难点啊。可能在编译时，就要生成一个中间文件，用来存放已编译的文本，然后当代码注释有修改时，更新xml时通过这中间文件来判断差异的地方。

[stratosblue]

指定一个目录专门放置xml文件，不同的语言用不同的文件名，然后在打包时放到对应目录中。

这个在demo里面已经有了，只不过不是按文件名，是按目录，这个还算好处理

只是这又要考虑增量修改的问题，如何做到已翻译过的不被改变，也是一个难点啊。

是准备人工维护吗？那确实还是需要一些投入的。。

可能在编译时，就要生成一个中间文件，用来存放已编译的文本，然后当代码注释有修改时，更新xml时通过这中间文件来判断差异的地方。

中间文件的话感觉不太好做，xml是可以多行或者内嵌其他东西的，不好做成其它的本地化KV形式文件。

可以做一个工具，在生成目标xml时，将原文hash之后放入对应节点的属性中，增量更新时再次将原文hash后对比目标文件对应节点是否已修改，如果已修改则替换为修改后的原始注释，然后人工通过代码对比工具进行校正。这种处理方式怎么样？大概像这样

[ElderJames]

这个方法确实不错，我都没想到👍 翻译问题，我想也可以在生成时调用翻译接口对文本进行翻译，然后也可以用相同的办法在节点上标记是人工的还是机器的，人工的除非hash更新了，否则不被机器更改。这样就可以循序渐进地进行翻译工作了。

[stratosblue]

嗯，感觉可行性还是不错的

[ElderJames]

不过我又不希望在编译时自动生成到开发目录，因为这样xml会经常变动。所以翻译应该是另一个命令，当需要更新时再统一更新。

[stratosblue]

肯定的，自动生成变动可能太多，影响代码历史记录。应该是另一个工具来维护，甚至新开个项目单独维护，使用submodule等方式引用也不是不行

[ElderJames]

是的，甚至是类似本项目，指定任意一个package来生成多语言xml

[stratosblue]

如果仅仅是翻译的话倒是可以比较简单的集成到这个项目，不过带上维护什么的功能的话，就不太好集成了

[ElderJames]

那可以另外做个MSBuild？或者源生成器，这样用户安装上这个包就能实现功能

[stratosblue]

嗯，我周末看看能不能把之前说的功能做到这个工具里面

[ElderJames]

太好了！到时有什么疑问，可以加我微信讨论，JamesYeungMVP

[stratosblue]

准备新增一个 translate 命令，接受参数

• file: 原始xml文件

• server: 翻译服务地址

• locales: 目标区域名列表

• content-compare: 内容对比模式

• separate-line: 换行分隔符

• output: 输出根目录

• parallel-count: 并发数量

• patch: 是否为增量模式

---

处理逻辑

• 处理时需要翻译内容会放在Body内Post到翻译服务地址，并将其返回Body作为翻译后内容，也就是说这个工具暂时不包含翻译相关的内容
• 输出时会在输出根目录按目标区域建立子目录，然后在里面生成同名xml
• 输出时会将输出xml按member的name进行排序，以确保增、删、移动位置等不会导致输出xml的结构发生较大变化，便于对比差异
• 输出时会在翻译过的节点增加属性 v (version) ，其值为原始节点innerXML Trim前后空白后的文本CRC64的BASE62字符串，用于Patch模式时对比是否需要处理
• Patch模式时会删除已不存在的节点，并新增新的节点
• Patch模式时会获取目标节点属性 i (ignore)，其值若为 1，则跳过该节点
• Patch模式时会对比属性 v ，属性不存在或内容不相等，则处理该节点

你看下这个样子满足需求不？

[ElderJames]

👍 看起来设计得很周全，再加上兼容打包发布的流程，就能实现很完整的流水线了。

另外，对于这些参数，可能需要设计一个配置文件，保留在项目中。这样方便贡献者在本地安装本cli，更新xml不必再配置输入输出目录等与项目相关的参数。

[stratosblue]

1.2.0版本已发，不过仅经过了非常有限的测试。。。

islocalizer.exe translate -h 可以看新命令的参数

实现和设计有一些差异

• locales参数现在有两个，分别为源文件区域from-locale，目标区域target-locales
• 版本计算由CRC64变更为CRC32

[stratosblue]

另外实现了一个简单的翻译服务端（仅测试了中英翻译） https://github.com/stratosblue/IntelliSenseLocalizer/tree/main/src/SimpleTranslateServer 使用阿里的翻译服务，配置 AliAccessKeyId 和 AliAccessKeySecret 就能运行

[ElderJames]

太好了，请问能做个简单的demo演示下用法吗？从创建、生成文件、翻译，最后到打包发布

[stratosblue]

嗯，从维护xml文件到nuget打包的demo吗？

[ElderJames]

是的，看看能否满足更新。我建议增加一个配置文件，里面配置源xml目录和翻译后的目录，再配置受支持的语言列表，这样在发布版本时就可以在ci里执行翻译了。

[stratosblue]

啊。。。没考虑在CI里维护的事情呢，之前不是说会放到代码管理里面手动维护的吗？

DEMO你看下行不行，主要是根目录的脚本和csproj里面的两个配置 MultiLanguageIntellisensePackage.zip

[ElderJames]

试了下，好像没有看到hash? 我是想手动的维护一份，但当api变动的时候，在ci打包的时候，能把新的变动（英文）和在源码中的注释翻译合并起来，这样能适应保持注释最新，翻译落后的情况。

[stratosblue]

好吧，在pipeline里面直接加语言和设置输出目录也是可以的，不一定要配置文件，hash我这测试是有的

[ElderJames]

我在我的项目中尝试了，貌似这个翻译服务不支持繁体...可能需要用open cc了

[ElderJames]

我觉得还需要发布卫星包，不然目前一个文件差不多300k,3个语言，5个tfm，打包就多出5MB。后期如果社区反应热烈，可能还要生成更多。

[stratosblue]

OpenCC还是比较好做的，如果需要的话我可以加到SimpleTranslateServer里面

nuget是zip压缩包，理论文本压缩率能达到50%-90%，这块要看一下最终打包出来的nuget包大小，这边.net的LanguagePack原始文件80M+，打包后只有8M+

智能感知文件卫星包麻烦些，不像资源文件直接放到最终输出目录就行了，智能感知文件需要放到nuget包缓存的dll所在目录，不过还是能做的

[ElderJames]

嗯嗯，这个可以放到工具里哈，有个类库 https://github.com/CosineG/OpenCC.NET

[stratosblue]

😅阿里的翻译说不定是支持繁体的，应该是我把区域信息截取掉的原因，我晚上看看。。。

[ElderJames]

好的！ 另外就是真实项目的xml文件太长了，后期想人工维护都不好做。是不是可以生成个中间文件来做维护比较好？当然也可以开发另外的UI来处理，类似生成API文档。

[ElderJames]

我尝试在项目中使用，但发布nuget包后，目录下创建了相同命名的xml，导致无法推送到nuget。

https://github.com/ant-design-blazor/ant-design-blazor/blob/master/components/AntDesign.csproj

[stratosblue]

我尝试在项目中使用，但发布nuget包后，目录下创建了相同命名的xml，导致无法推送到nuget。

https://github.com/ant-design-blazor/ant-design-blazor/blob/master/components/AntDesign.csproj

可以尝试取消

<GenerateDocumentationFile>true</GenerateDocumentationFile>

或者在 TfmSpecificPackageFile 里面 exclude掉 LocalizedIntellisenseFiles/$(AssemblyName).xml

应该都是可行的（没试。。）

[stratosblue]

好的！ 另外就是真实项目的xml文件太长了，后期想人工维护都不好做。是不是可以生成个中间文件来做维护比较好？当然也可以开发另外的UI来处理，类似生成API文档。

可以考虑，但是量大了应该还是会变得不好维护 😂

[ElderJames]

去掉 <GenerateDocumentationFile>true</GenerateDocumentationFile> 可以了

[ElderJames]

是的，所以还是弄个维护用的UI好了，可以按照目录、类名等等分类折叠，然后再加个处理进度之类的。

[stratosblue]

阿里的翻译支持繁体 zh-tw ，SimpleTranslateServer已修正

是的，所以还是弄个维护用的UI好了，可以按照目录、类名等等分类折叠，然后再加个处理进度之类的。

这个的话就有点复杂了，可以新开个坑来做了，属于是一个类库开发者辅助工具。

我觉得还需要发布卫星包，不然目前一个文件差不多300k,3个语言，5个tfm，打包就多出5MB。后期如果社区反应热烈，可能还要生成更多。

这个我突然想到可以减小一点空间。只在nuget包中存放一份各个语言的xml，然后用一个targets在用户使用时复制到nuget的dll缓存目录，理论上是可行的

[ElderJames]

这个我突然想到可以减小一点空间。只在nuget包中存放一份各个语言的xml，然后用一个targets在用户使用时复制到nuget的dll缓存目录，理论上是可行的

如果可行会不错！

另外今天给我们项目发布之后，发现有一些固定值也被翻译了，比如有的属性只希望传 default small large，或者就是 css 的属性值，这些也会被翻译。请问是不是应该用一些特定的标签来区分出来不 进行翻译？

[stratosblue]

打包的我有空再看看

翻译的话可以试试注释时使用这样的注释

<see langword="default"/>
<see langword=".main .large"/>

SimpleTranslateServer使用的html翻译，理论上不会碰这种标签内的内容（但我没试）