util dir little doc

util/README.en.md

@@ -0,0 +1,66 @@
+# Utilities
+
+[portuguese](README.md)
+
+This directory contains useful scripts to help with the PowershAI development and documentation process.
+
+# Tips
+
+## How to generate documentation from code (comments)?
+
+Use the Cmdlets2Markdown.ps1 script:
+
+```powershell
+. .\util\Cmdlets2Markdown.ps1 -Update
+```
+
+This will update all files in the docs/pt-BR/cmdlets directory.
+Direct documentation in the code is in pt-BR, as it is faster for me to document in my native language.
+But this may change in the future.  For now, we use pt-BR as the source for markdown and other language documentation.
+
+## How to translate files in docs/ to other languages?
+
+The aidoc.ps1 script can help generate an automatic translation.
+It uses powershai itself to send the data to the desired provider and update the files.
+It keeps controls to avoid sending files that haven't been changed, or trying to overwrite files that have already been changed by someone.
+
+How to use:
+
+- Create the desired language directory in docs/, if it doesn't exist. This tells the script that this language is supported. Use the BCP 47 code (aa-BB format)
+- Choose a provider and model that support large amounts of context. Particularly, I have been doing it with Google Gemini Flash 1.5, which has a context of about 1M, low cost and very good results.
+
+Having made these prerequisites, run the script, examples:
+
+```
+# Example 
+.\util\aidoc.ps1 -SourceLang pt-BR -TargetLang en-US -Provider google -MaxTokens 32000
+```
+
+Note that I am using pt-BR as the source.
+I always use pt-BR as the source, as it is the language in which I trust the content at the moment.
+
+### Important about documentation translation with AI
+
+Note that this process tends to be automatic, you may not need to worry (but, if you want to learn and study a practical use of powershai, it's a good test).
+Just remember that using the provider can incur costs.
+The costs of the translations done so far have been paid by the project author, Rodrigo, using his own tokens.
+Keep in mind that, when doing tests, you will use your own tokens, and therefore, you will have your own cost (and there is no guarantee that these modifications will be approved).
+
+## How to generate compiled Powershell documentation from docs/
+
+The doc.ps1 script was created to convert documentation in docs/ to compiled Powershell help that can be distributed with the module.
+This is a process that I am still testing, and therefore, there is nothing being published.
+
+The doc.ps1 script performs several validations and adjustments to adapt the files in docs/ to the format expected by PlatyPS.
+PlatyPs is a module that helps generate documentation in the Powershell MAML format, compiled into .xml
+
+```
+.\util\doc.ps1 -WorkDir T:\platy -SupportedLangs ja-JP  -MaxAboutWidth 150
+```
+
+`workDir` is a temporary directory where it will copy and modify the files, as well as use as a stage for the process.
+`SupportedLangs` is a list of languages you want to generate.
+`MaxAboutWidth` controls the maximum size of a line. PlatyPS can generate an error due to a module bug, and increasing the MaxAboutWidth can prevent this error.
+``` you want to generate.
+`MaxAboutWidth` controls the maximum size of a line. PlatyPS can generate an error due to a module bug, and increasing the MaxAboutWidth can prevent this error.
+```

util/README.md

@@ -1,5 +1,67 @@
-# Utilities
+# Utilidades
+
+[english](README.en.md)
+
+Este diretório contém scrips úteis, para ajudar no processo de desenvolvimento e documentação do PowershAI.  
+
+# Dicas
+
+## Como gerar a doc a partir do código (coentários)?  
+
+Use o script Cmdlets2Markdown.ps1:  
+
+```powershell
+. .\util\Cmdlets2Markdown.ps1 -Update
+```
+
+Isso vai atualizar todos os arquivos no diretório docs/pt-BR/cmdlets  
+A documentação direta no código está em pt-BR, pois é mais rápido para mim documentar no meu idioma nativo.  
+Mas isso pode mudar no futuro.  Por enquanto, usamos a pt-BR como fonte para a documentação em markdonw e outras linguagens.  
+
+## Como traduzi os arquivos em docs/ para outros idiomas?
+
+O script aidoc.ps1 pode ajudar a gerar uma tradução automática.  
+Ele usa o próprio powershai para enviar os dados ao provider desejado e atualizar os arquivos.  
+Ele mantém controles para evitar enviar arquivos que não foram alterados, ou tentar sobrescrever arquivos que já foram alterados por alguém.  
+
+Como usar:
+
+- Crie o diretório do idioma desejado em docs/, se ele não existe. ISso diz ao script que esse idioma é suportado. Usar o código BCP 47 (formato aa-BB)
+- Escolha um provider e modelo que suportam grandes quantidade de contexto. Particulamente, eu tenho feito com o Google Gemini Flash 1.5, que tem um contexto muito de 1M, custo baixo e um resultado muito bom.
+
+Tendo feito esses pré-requisitos, rode o script, exemplos:
+
+```
+# Example 
+.\util\aidoc.ps1 -SourceLang pt-BR -TargetLang en-US -Provider google -MaxTokens 32000
+```
+
+Note que estou uando pt-BR como origem.  
+Eu sempre uso pt-BR como origem, pois é a linguagem em que confio o contéudo no momento.  
+
+### Importante sobre a tradução da documentação com IA
+
+Note que esse processo tende a ser automático, você talvez não precise se preocupar (mas, caso queria aprender e estudar um uso prático do powershai, é um bom teste).  
+Apenas lembre-se que usar o provider pode incorrer custos.  
+Os custos das traduções que feitas até aqui, foram pagos pelo autor do projeto, Rodrigo, usando seus próprios tokens.  
+Tenha em mente que, ao fazer testes, você usará seus próprios tokens, e por isso, terá o seu próprio custo (e não há garantia que essas modificações serão aprovadas).  
+
+
+
+## Como gerar a doc compilada do Powershell a partir de docs/  
+
+O script doc.ps1 foi criado para converter a doc em docs/ para um help compialdo do powershell que pode ser distribuído junto com módulo.  
+Este éum process que estou testando ainda, e, por isso, não há nada sendo publicado.  
+
+O script doc.ps1 faz diversas validações e ajustes para adaptar os arquivos em docs/ para o formato esperado pelo PlatyPS.  
+PlatyPs é um módulo que ajuda a gerar a documentação no formao MAML do powershell, compilada no .xml  
+
+```
+.\util\doc.ps1 -WorkDir T:\platy -SupportedLangs ja-JP  -MaxAboutWidth 150
+```
+
+`workDir` é um diretorio temporário onde ele irá copiar e modificar os arquivos, além de usar como stage do processo.  
+`SupportedLangs` é uma lista de idiomas que quer gerar.  
+`MaxAboutWidth` controla o tamanho máximo de uma linha. O PlatyPS pode gerar um erro devido a um bug do módulo,e  aumentar o MaxAboutWidth pode evitar esse erro.  
 
-This directory contains utility scripts only to be used to help development of powershai.
 
-