docs: Translate README and examples to Portuguese

- Translate README.md: All sections including decision table ("Qual Módulo Devo Usar?") and FAQ ("Perguntas Frequentes")
- Translate examples/sgs_time_series.py: docstring and all inline comments
- Translate examples/currency_exchange.py: docstring and all inline comments
- Translate examples/odata_query.py: docstring and all inline comments
- Translate examples/async_usage.py: docstring and all inline comments

All 4 example scripts now have full Portuguese documentation while maintaining code functionality.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Author: wilsonfreitas

README.md

@@ -9,7 +9,6 @@ da API de dados abertos do [Banco Central do Brasil](https://www.bcb.gov.br).
 ![Lint workflow](https://github.com/wilsonfreitas/python-bcb/actions/workflows/lint.yml/badge.svg)
 ![Sphinx workflow](https://github.com/wilsonfreitas/python-bcb/actions/workflows/sphinx.yml/badge.svg)
 
-
 O projeto de [Dados Abertos do Banco Central do Brasil](https://dadosabertos.bcb.gov.br/)
 disponibiliza diversas APIs provendo acesso direto a dados de:
 
@@ -18,108 +17,96 @@ disponibiliza diversas APIs provendo acesso direto a dados de:
 * Índices de preços
 * Informações de Instituições Financeiras
 * Expectativas do Mercado (Expectativas do Boletim FOCUS)
-* E muito outros ...
+* E muito mais...
 
-# Instalação
+## Instalação
 
-**python-bcb** está disponível no [Python Package Index](https://pypi.org/project/python-bcb/) e pode ser instalado via `pip` usando.
+**python-bcb** está disponível no [Python Package Index](https://pypi.org/project/python-bcb/) e pode ser instalado via `pip`.
 
 ```shell
 pip install python-bcb
 ```
 
-# APIs
-
-
-## SGS
-Utiliza o webservice do SGS
-([Sistema Gerenciador de Séries Temporais](https://www3.bcb.gov.br/sgspub/))
-para obter os dados.
+## APIs
 
-## Conversor de Moedas
+### SGS - Sistema Gerenciador de Séries Temporais
 
-Implementado no módulo `currency`, um conjunto de funções que realiza webscraping
-no site do [Conversor de Moedas](https://www.bcb.gov.br/conversao)
-do Banco Central, possível obter séries temporais de frequência diária
-de diversas moedas.
+Utiliza o webservice do SGS ([Sistema Gerenciador de Séries Temporais](https://www3.bcb.gov.br/sgspub/)) para obter dados históricos de indicadores econômicos. Oferece a maior base de dados históricos com diversas séries temporais.
 
-## Moedas OData
+### Conversor de Moedas
 
-O Banco Central disponibiliza diversas informações em APIs que
-seguem o padrão [OData](https://odata.org).
-A classe `bcb.PTAX` implementa uma API OData que
-entrega os boletins diários de taxas de câmbio do Banco Central.
-Esta API entrega mais informações do que o que é obtido no
-`Conversor de Moedas`.
+Implementado no módulo `currency`, realiza webscraping no site do [Conversor de Moedas](https://www.bcb.gov.br/conversao) do Banco Central. Fornece séries temporais de frequência diária de taxas de câmbio (cotações de compra e venda).
 
-## Expectativas
+### OData - APIs Estruturadas
 
-A API de Expectativas de Mercado traz todas as estatísticas das variáveis
-macroeconômicas fornecidos por um conjuto de instituições do mercado
-financeiro.
-A classe `bcb.Expectativas` implementa essa interface no
-padrão OData.
+O Banco Central disponibiliza diversas informações em APIs que seguem o padrão [OData](https://odata.org). Inclui:
+- **PTAX**: Boletins diários de taxas de câmbio com dados institucionalmentedetalhados
+- **Expectativas**: Expectativas de mercado coletadas do Boletim FOCUS
+- **TaxaJuros**: Diversas taxas de juros (Selic, CDI, Cheque especial, etc.)
+- **MercadoImobiliario**: Dados de financiamento imobiliário
+- **IFDATA**: Informações de instituições financeiras
+- **SPI**: Sistema de Pagamentos Instantâneos
 
-# Which Module Should I Use?
+## Qual Módulo Devo Usar?
 
-Use this table to choose the right module for your use case:
+Use esta tabela para escolher o módulo certo para seu caso de uso:
 
-| Use Case | Module | Key Features |
+| Caso de Uso | Módulo | Características Principais |
 |----------|--------|--------------|
-| Daily time series (inflation, interest rates) | `bcb.sgs` | Largest historical dataset, granular frequency control, multiple pre-defined series |
-| Daily foreign exchange rates (PTAX) | `bcb.currency` | Bid/ask spreads, quick implementation, daily frequency |
-| Market expectations (FOCUS survey) | `bcb.odata` (Expectativas) | Forward-looking economic indicators, consensus forecasts |
-| Interest rates (various types) | `bcb.odata` (TaxaJuros) | Detailed rate curves, real estate lending rates |
-| Real estate financing data | `bcb.odata` (MercadoImobiliario) | Mortgage originations, average rates, volumes |
-| Financial institution information | `bcb.odata` (IFDATA) | Bank balance sheet data, regulatory information |
-| Advanced data analysis with filters | `bcb.odata` (any service) | Chainable API, SQL-like filtering, sorting, selection |
-| Concurrent data fetching | Any module with `async_get()` | Non-blocking requests, improved performance for bulk operations |
+| Séries temporais diárias (inflação, taxas de juros) | `bcb.sgs` | Maior base histórica, controle granular de frequência, múltiplas séries pré-definidas |
+| Taxas de câmbio diárias (PTAX) | `bcb.currency` | Spreads de compra/venda, implementação rápida, frequência diária |
+| Expectativas de mercado (Boletim FOCUS) | `bcb.odata` (Expectativas) | Indicadores de expectativas, previsões de consenso |
+| Taxas de juros (diversos tipos) | `bcb.odata` (TaxaJuros) | Curvas detalhadas, taxas de financiamento imobiliário |
+| Dados de financiamento imobiliário | `bcb.odata` (MercadoImobiliario) | Originações, taxas médias, volumes |
+| Informações de instituições financeiras | `bcb.odata` (IFDATA) | Dados de balanço, informações regulatórias |
+| Análise de dados avançada com filtros | `bcb.odata` (qualquer serviço) | API encadeável, filtragem tipo SQL, ordenação, seleção |
+| Busca concorrente de dados | Qualquer módulo com `async_get()` | Requisições não-bloqueantes, melhor performance para operações em massa |
 
-# Quick Start
+## Início Rápido
 
-## Time Series with SGS
+### Séries Temporais com SGS
 
 ```python
 from bcb import sgs
 
-# Fetch SELIC rate (code 1)
+# Buscar taxa Selic (código 1)
 df = sgs.get(1, start="2023-01-01", end="2024-12-31")
 ```
 
-## Exchange Rates with Currency
+### Taxas de Câmbio com Currency
 
 ```python
 from bcb import currency
 
-# Fetch USD bid/ask prices
+# Buscar preços de compra/venda do USD
 usd = currency.get("USD", start="2023-01-01", end="2024-12-31")
 ```
 
-## Market Expectations with OData
+### Expectativas de Mercado com OData
 
 ```python
 from bcb import Expectativas
 
 api = Expectativas()
 endpoint = api.get_endpoint("ExpectativasMercadoAnuais")
 
-# Get IPCA forecasts
+# Obter previsões do IPCA
 df = endpoint.query().filter(endpoint.Indicador == "IPCA").limit(100).collect()
 ```
 
-# FAQ
+## Perguntas Frequentes
 
-## Q: What's the difference between SGS and PTAX currency data?
-**A:** SGS contains mostly economic indicators. For currency exchange rates, use `bcb.currency` (PTAX data) for daily rates or `bcb.odata` PTAX service for detailed institutional data. The currency module is simpler for common use cases.
+### P: Qual é a diferença entre dados de moedas do SGS e PTAX?
+**R:** SGS contém principalmente indicadores econômicos. Para taxas de câmbio, use `bcb.currency` (dados PTAX) para cotações diárias ou o serviço `bcb.odata` PTAX para dados institucionais detalhados. O módulo currency é mais simples para casos comuns.
 
-## Q: How far back does historical data go?
-**A:** It varies by series:
-- SGS: Most series go back to 1980s or 1990s (check specific code documentation)
-- Currency: Daily rates available from approximately 1980
-- OData services: Varies; check BCB documentation for specific endpoints
+### P: Quão longe no tempo os dados históricos vão?
+**R:** Varia por série:
+- SGS: Maioria das séries remontam aos anos 1980/1990 (verifique documentação específica do código)
+- Currency: Cotações diárias disponíveis desde aproximadamente 1980
+- Serviços OData: Varia; consulte documentação BCB para endpoints específicos
 
-## Q: Can I fetch data asynchronously?
-**A:** Yes! All modules have `async_get()` or similar async methods. Use them for concurrent requests:
+### P: Posso buscar dados de forma assíncrona?
+**R:** Sim! Todos os módulos têm métodos `async_get()` ou similares. Use-os para requisições concorrentes:
 ```python
 import asyncio
 from bcb import sgs
@@ -133,60 +120,60 @@ async def main():
 asyncio.run(main())
 ```
 
-## Q: How do I handle errors/missing data?
-**A:** The library raises specific exceptions:
-- `CurrencyNotFoundError`: Currency symbol not found
-- `SGSError`: SGS service error
-- `BCBRateLimitError`: Rate limit exceeded (HTTP 429)
-- `BCBAPIError`: Other API errors
+### P: Como trato erros e dados faltantes?
+**R:** A biblioteca lança exceções específicas:
+- `CurrencyNotFoundError`: Símbolo de moeda não encontrado
+- `SGSError`: Erro do serviço SGS
+- `BCBRateLimitError`: Limite de requisições excedido (HTTP 429)
+- `BCBAPIError`: Outros erros de API
 
 ```python
 from bcb import sgs
 from bcb.exceptions import SGSError, BCBRateLimitError
 
 try:
-    df = sgs.get(99999)  # Invalid code
+    df = sgs.get(99999)  # Código inválido
 except SGSError as e:
-    print(f"Data error: {e}")
+    print(f"Erro de dados: {e}")
 except BCBRateLimitError:
-    print("Rate limited - please try again later")
+    print("Limite de requisições excedido - tente novamente mais tarde")
 ```
 
-## Q: How do I enable logging to debug requests?
-**A:** The library uses Python's standard logging module:
+### P: Como habilito logging para depurar requisições?
+**R:** A biblioteca usa o módulo logging padrão do Python:
 ```python
 import logging
 
 logging.basicConfig(level=logging.DEBUG)
 logger = logging.getLogger("bcb")
 logger.setLevel(logging.DEBUG)
 
-# Now all HTTP requests/responses will be logged
+# Agora todas as requisições/respostas HTTP serão registradas
 ```
 
-## Q: Is there caching to avoid redundant requests?
-**A:** Yes:
-- `bcb.currency`: Automatic in-memory cache of currency lists
-- `bcb.odata`: OData metadata cached per service URL
-- Call `currency.clear_cache()` to reset if data changes
-
-## Q: Can I use this in a long-running application?
-**A:** Yes, but be mindful of:
-- Rate limits: BCB APIs may have limits; implement backoff if needed
-- Caching: Currency cache persists in memory; clear it if data updates matter
-- Connection pooling: Uses httpx with connection pooling by default
-- Async API: Use async methods for truly non-blocking behavior
-
-## Q: How do I contribute or report issues?
-**A:** Visit the [GitHub repository](https://github.com/wilsonfreitas/python-bcb) to:
-- Report bugs
-- Request features
-- Submit pull requests
-- View documentation
-
-## Q: Where can I find more detailed documentation?
-**A:**
-- [API Documentation](https://bcb-python.readthedocs.io/)
-- [Examples Directory](./examples/)
-- Inline docstrings: `help(bcb.sgs.get)`, `help(bcb.currency.get)`, etc.
-- [BCB Open Data Portal](https://dadosabertos.bcb.gov.br/)
+### P: Existe cache para evitar requisições redundantes?
+**R:** Sim:
+- `bcb.currency`: Cache em memória automático de listas de moedas
+- `bcb.odata`: Metadados OData em cache por URL de serviço
+- Chame `currency.clear_cache()` para resetar se dados mudarem
+
+### P: Posso usar isso em uma aplicação de longa duração?
+**R:** Sim, mas tenha cuidado com:
+- Limites de requisições: APIs BCB podem ter limites; implemente backoff se necessário
+- Cache: Cache de moedas persiste em memória; limpe se atualizações de dados importarem
+- Pool de conexões: Usa httpx com connection pooling por padrão
+- API Assíncrona: Use métodos async para comportamento verdadeiramente não-bloqueante
+
+### P: Como contribuo ou reporto problemas?
+**R:** Visite o [repositório GitHub](https://github.com/wilsonfreitas/python-bcb) para:
+- Reportar bugs
+- Solicitar features
+- Enviar pull requests
+- Ver documentação
+
+### P: Onde encontro documentação mais detalhada?
+**R:**
+- [Documentação de API](https://bcb-python.readthedocs.io/)
+- [Diretório de Exemplos](./examples/)
+- Docstrings inline: `help(bcb.sgs.get)`, `help(bcb.currency.get)`, etc.
+- [Portal de Dados Abertos BCB](https://dadosabertos.bcb.gov.br/)

examples/async_usage.py

@@ -1,8 +1,8 @@
 """
-Example: Using Async APIs
+Exemplo: Usando APIs Assíncronas
 
-This example demonstrates how to use the async versions of the APIs
-for concurrent data fetching (useful for fetching multiple series).
+Este exemplo demonstra como usar as versões assíncronas das APIs
+para busca de dados concorrente (útil para buscar múltiplas séries).
 """
 
 import asyncio
@@ -12,76 +12,76 @@
 
 
 async def fetch_multiple_sgs_series():
-    """Fetch multiple SGS time series concurrently."""
-    print("Example 1: Fetching multiple SGS series concurrently")
+    """Buscar múltiplas séries temporais do SGS concorrentemente."""
+    print("Exemplo 1: Buscando múltiplas séries do SGS concorrentemente")
 
-    # Fetch SELIC, CDI, and IPCA concurrently
+    # Buscar SELIC, CDI e IPCA concorrentemente
     codes = [1, 12, 433]  # SELIC, CDI, IPCA
 
     df = await sgs.async_get(codes, start="2023-01-01", end="2024-12-31", multi=True)
-    print("Concurrent SGS fetch completed")
+    print("Busca concorrente do SGS concluída")
     print(df.head())
     print()
 
 
 async def fetch_multiple_currencies():
-    """Fetch currency rates concurrently."""
-    print("Example 2: Fetching currency rates concurrently")
+    """Buscar taxas de câmbio concorrentemente."""
+    print("Exemplo 2: Buscando taxas de câmbio concorrentemente")
 
-    # Fetch USD rate (note: you'd need to implement multi-symbol async
-    # for this to truly be concurrent for different symbols)
+    # Buscar taxa do USD (nota: você precisaria implementar async multi-símbolo
+    # para isso ser verdadeiramente concorrente para diferentes símbolos)
     df = await currency.async_get("USD", start="2024-01-01", end="2024-12-31")
-    print("Async currency fetch completed")
+    print("Busca de câmbio assíncrona concluída")
     print(df.head())
     print()
 
 
 async def fetch_odata_async():
-    """Fetch OData results asynchronously."""
-    print("Example 3: Fetching OData results asynchronously")
+    """Buscar resultados OData de forma assíncrona."""
+    print("Exemplo 3: Buscando resultados OData de forma assíncrona")
 
     api = Expectativas()
     endpoint = api.get_endpoint("ExpectativasMercadoAnuais")
 
-    # Build and execute query asynchronously
+    # Construir e executar consulta de forma assíncrona
     query = endpoint.query().filter(endpoint.Indicador == "IPCA").limit(5)
     df = await query.async_collect()
-    print("Async OData fetch completed")
+    print("Busca OData assíncrona concluída")
     print(df)
     print()
 
 
 async def concurrent_operations():
-    """Execute multiple async operations concurrently."""
-    print("Example 4: Multiple concurrent operations")
+    """Executar múltiplas operações assíncronas concorrentemente."""
+    print("Exemplo 4: Múltiplas operações concorrentes")
 
-    # Create tasks for concurrent execution
+    # Criar tarefas para execução concorrente
     tasks = [
         sgs.async_get(1, start="2024-01-01", end="2024-12-31"),  # SELIC
         sgs.async_get(11, start="2024-01-01", end="2024-12-31"),  # CDI
         sgs.async_get(433, start="2024-01-01", end="2024-12-31"),  # IPCA
     ]
 
-    # Wait for all tasks to complete
+    # Aguardar conclusão de todas as tarefas
     results = await asyncio.gather(*tasks)
-    print(f"Fetched {len(results)} concurrent series")
-    print("First series sample:")
+    print(f"Buscadas {len(results)} séries concorrentes")
+    print("Amostra da primeira série:")
     print(results[0].head())
     print()
 
 
 async def main():
-    """Run all async examples."""
+    """Executar todos os exemplos assíncronos."""
     try:
         await fetch_multiple_sgs_series()
         await fetch_multiple_currencies()
         await fetch_odata_async()
         await concurrent_operations()
     except Exception as e:
-        print(f"Error: {type(e).__name__}: {e}")
+        print(f"Erro: {type(e).__name__}: {e}")
 
 
 if __name__ == "__main__":
-    # Run the async examples
-    # Note: This requires Python 3.7+ with asyncio
+    # Executar os exemplos assíncronos
+    # Nota: Isso requer Python 3.7+ com asyncio
     asyncio.run(main())