docs: polish translation

docs/.vitepress/config/index.ts

@@ -1,16 +1,18 @@
-import { defineConfig } from 'vitepress'
-import { enConfig } from './en'
-import { esConfig } from './es'
-import { sharedConfig } from './shared'
+import { defineConfig } from "vitepress";
+import { enConfig } from "./en";
+import { esConfig } from "./es";
+import { plConfig } from "./es";
+import { sharedConfig } from "./shared";
 
 /* import { zhConfig } from './zh' */
 
 export default defineConfig({
   ...sharedConfig,
 
   locales: {
-    root: { label: 'English', lang: 'en-US', link: '/', ...enConfig },
-    es: { label: 'Español', lang: 'es-ES', link: '/es/', ...esConfig },
+    root: { label: "English", lang: "en-US", link: "/", ...enConfig },
+    es: { label: "Español", lang: "es-ES", link: "/es/", ...esConfig },
+    pl: { label: "Polish", lang: "pl-PL", link: "/pl/", ...plConfig },
     /* zh: { label: '简体中文', lang: 'zh-CN', link: '/zh/', ...zhConfig }, */
   },
-})
+});

docs/.vitepress/config/pl.ts

@@ -0,0 +1,153 @@
+import type { DefaultTheme, LocaleSpecificConfig } from "vitepress";
+
+export const plConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
+  themeConfig: {
+    editLink: {
+      pattern: "https://github.com/tresjs/tres/edit/main/packages/docs/:path",
+      text: "Zaproponuj zmiany na tej stronie",
+    },
+    sidebar: [
+      {
+        text: "Przewodnik",
+        items: [
+          // Esto muestra la página `/guide/index.md`.
+          { text: "Wstęp", link: "/pl/guide/" },
+          { text: "Pierwsze kroki", link: "/pl/guide/getting-started" },
+          { text: "Twoja pierwsza scena", link: "/pl/guide/your-first-scene" },
+          { text: "Nuxt", link: "/pl/guide/nuxt" },
+          {
+            text: "Rozwiązywanie problemów",
+            link: "/pl/guide/troubleshooting",
+          },
+          { text: "Migracja z v1", link: "/pl/guide/migration-guide" },
+        ],
+      },
+      {
+        text: "API",
+        items: [
+          { text: "TresCanvas", link: "/pl/api/tres-canvas" },
+          {
+            text: "Instancje, argumenty i właściwości",
+            link: "/pl/api/instances-arguments-and-props",
+          },
+          {
+            text: "Komponowalne",
+            link: "/pl/api/composables",
+          },
+          {
+            text: "Wydarzenia",
+            link: "/pl/api/events",
+          },
+        ],
+      },
+
+      {
+        text: "Zaawansowany",
+
+        items: [
+          { text: "Rozszerzanie", link: "/pl/advanced/extending" },
+          { text: "Prymitywny", link: "/pl/advanced/primitive" },
+          {
+            text: "Zastrzeżenia",
+            link: "/pl/advanced/caveats",
+          },
+        ],
+      },
+      {
+        text: "Znajdowanie",
+        items: [
+          { text: "Narzędzia deweloperskie", link: "/pl/debug/devtools" },
+        ],
+      },
+      {
+        text: "Książka kucharska 🍳🧑‍🍳",
+        collapsed: true,
+        items: [
+          { text: "Sterowanie orbitą", link: "/pl/cookbook/orbit-controls" },
+          {
+            text: "Podstawowe animacje",
+            link: "/pl/cookbook/basic-animations",
+          },
+          { text: "Grupy", link: "/pl/cookbook/groups" },
+          { text: "Ładowanie tekstur", link: "/pl/cookbook/load-textures" },
+          { text: "Ładowanie modelu", link: "/pl/cookbook/load-models" },
+          { text: "Ładowanie tekstu", link: "/pl/cookbook/text-3d" },
+          { text: "Światła i cienie", link: "/pl/cookbook/lights-shadows" },
+          { text: "Shadery", link: "/pl/cookbook/shaders" },
+        ],
+      },
+      {
+        text: "Dyrektywy",
+        collapsed: true,
+        items: [
+          { text: "v-log", link: "/pl/directives/v-log" },
+          { text: "v-light-helper", link: "/pl/directives/v-light-helper" },
+          { text: "v-always-look-at", link: "/pl/directives/v-always-look-at" },
+          { text: "v-distance-to", link: "/pl/directives/v-distance-to" },
+        ],
+      },
+      {
+        text: "Ekosystem",
+        items: [
+          {
+            text: "Cientos 💛",
+            link: "https://cientos.tresjs.org/",
+          },
+          {
+            text: "Nuxt module",
+            link: "https://github.com/Tresjs/nuxt",
+          },
+          {
+            text: "TresLeches 🍰",
+            link: "https://tresleches.tresjs.org/",
+          },
+          {
+            text: "Post-processing (wkrótce)",
+          },
+        ],
+      },
+    ],
+    nav: [
+      { text: "Przewodnik", link: "/pl/guide/" },
+      { text: "API", link: "/pl/api/tres-canvas" },
+      /*       { text: 'API', link: '/pl/api/' },
+      { text: 'Konfiguracja', link: '/pl/config/' }, */
+      {
+        text: "Zasoby",
+        items: [
+          { text: "Zespół", link: "/pl/team" },
+          { text: "Wydania", link: "https://github.com/Tresjs/tres/releases" },
+          {
+            text: "Plac zabaw",
+            link: "https://playground.tresjs.org/",
+          },
+          {
+            text: "Github",
+            link: "https://github.com/Tresjs/tres/",
+          },
+          {
+            text: "Problemy",
+            link: "https://github.com/Tresjs/tres/issues",
+          },
+          {
+            text: "Ekosystem",
+            items: [
+              {
+                text: "Cientos 💛",
+                link: "https://cientos.tresjs.org/",
+              },
+              {
+                text: "Módulo Nuxt",
+                link: "https://github.com/Tresjs/nuxt",
+              },
+              {
+                text: "TresLeches 🍰",
+                link: "https://tresleches.tresjs.org/",
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+};

docs/es/examples/load-textures.md

@@ -15,10 +15,10 @@ El composable `useLoader` te permite pasar cualquier tipo de cargador de three.j
 Para obtener una explicación detallada de cómo usar `useLoader`, consulta la documentación de [useLoader](/api/composables#use-loader).
 
 ```ts
-import { useLoader } from '@tresjs/core'
-import { TextureLoader } from 'three'
+import { useLoader } from "@tresjs/core";
+import { TextureLoader } from "three";
 
-const texture = useLoader(TextureLoader, '/Rock035_2K_Color.jpg')
+const texture = useLoader(TextureLoader, "/Rock035_2K_Color.jpg");
 ```
 
 Luego puedes pasar la textura a un material:
@@ -43,20 +43,19 @@ Una forma más conveniente de cargar texturas es utilizando el composable `useTe
 Para obtener más información sobre `useTexture`, consulta la documentación de [useTexture](/api/composables#use-texture).
 
 ```ts
-import { useTexture } from '@tresjs/core'
+import { useTexture } from "@tresjs/core";
 
 const pbrTexture = await useTexture({
-  map: '/textures/black-rock/Rock035_2K_Displacement.jpg',
-  displacementMap: '/textures/black-rock/Rock035_2K_Displacement.jpg',
-  roughnessMap: '/textures/black-rock/Rock035_2K_Roughness.jpg',
-  normalMap: '/textures/black-rock/Rock035_2K_NormalDX.jpg',
-  aoMap: '/textures/black-rock/Rock035_2K_AmbientOcclusion.jpg',
-  metalnessMap: '/textures/black-rock/myMetalnessTexture.jpg',
-  matcap: '/textures/black-rock/myMatcapTexture.jpg',
-  alphaMap: '/textures/black-rock/myAlphaMapTexture.jpg'
-})
+  map: "/textures/black-rock/Rock035_2K_Displacement.jpg",
+  displacementMap: "/textures/black-rock/Rock035_2K_Displacement.jpg",
+  roughnessMap: "/textures/black-rock/Rock035_2K_Roughness.jpg",
+  normalMap: "/textures/black-rock/Rock035_2K_NormalDX.jpg",
+  aoMap: "/textures/black-rock/Rock035_2K_AmbientOcclusion.jpg",
+  metalnessMap: "/textures/black-rock/myMetalnessTexture.jpg",
+  matcap: "/textures/black-rock/myMatcapTexture.jpg",
+  alphaMap: "/textures/black-rock/myAlphaMapTexture.jpg",
+});
 ```
-Similar to the previous example, we can pass all the textures to a material via props:
 
 Al igual que en el ejemplo anterior, podemos pasar todas las texturas a un material a través de props:
 

docs/guide/index.md

@@ -9,15 +9,15 @@
 ::: code-group
 
 ```bash [npm]
-npm install @tresjs/core three 
+npm install @tresjs/core three
 ```
 
 ```bash [yarn]
-yarn add @tresjs/core three 
+yarn add @tresjs/core three
 ```
 
 ```bash [pnpm]
-pnpm add @tresjs/core three 
+pnpm add @tresjs/core three
 ```
 
 :::
@@ -59,7 +59,7 @@ export default defineConfig({
 }),
 ```
 
-This is required to make the template compiler work with the custom renderer and not throw warnings on the console. For more info check [here](/guide/troubleshooting.html).
+This is required to make the template compiler work with the custom renderer and not throw warnings on the console. For more info check [here](/es/guide/troubleshooting.html).
 
 ## Try it online
 
@@ -95,20 +95,19 @@ The only problem is, mixing compilers renderers in Vue 3 is something the Vue co
 
 ```ts
 // Example Vite setup
-import { createApp } from 'vue'
-import { createApp as createLunchboxApp } from 'lunchboxjs'
-import App from './App.vue'
-import LunchboxApp from './LunchboxApp.vue'
+import { createApp } from "vue";
+import { createApp as createLunchboxApp } from "lunchboxjs";
+import App from "./App.vue";
+import LunchboxApp from "./LunchboxApp.vue";
 
 // html app
-const app = createApp(App)
-app.mount('#app')
+const app = createApp(App);
+app.mount("#app");
 
 // lunchbox app
-const lunchboxApp = createLunchboxApp(LunchboxApp)
+const lunchboxApp = createLunchboxApp(LunchboxApp);
 // assuming there's an element with ID `lunchbox` in your HTML app
-lunchboxApp.mount('#lunchbox')
+lunchboxApp.mount("#lunchbox");
 ```
 
 So I was inspired by both libraries to create a Vue custom renderer for ThreeJS. That's **TresJS v2**.
-

docs/pl/advanced/caveats.md

@@ -0,0 +1,109 @@
+# Ostrzeżenia 😱
+
+Naszym celem jest dostarczenie prostego sposobu korzystania z ThreeJS w VueJS z najlepszym możliwym doświadczeniem programistycznym. Niemniej jednak istnieją pewne ostrzeżenia, o których powinieneś być świadomy.
+
+## ~~HMR y ThreeJS~~
+
+:::info
+
+To zostało rozwiązane w **TresJS** v1.7.0 🎉. Teraz możesz używać HMR bez konieczności przeładowywania strony 🥹.
+
+:::
+
+Hot Module Replacement (HMR) to funkcja, która pozwala na aktualizowanie kodu bez ponownego ładowania strony. To świetna cecha, która znacznie przyspiesza proces developmentu. **TresJS** korzysta z [Vite](https://vitejs.dev/). Jednakże, jest to naprawdę skomplikowane, aby zadziałało poprawnie z ThreeJS.
+
+Dlaczego? Ponieważ Tres buduje scenę deklaratywnie. Oznacza to, że tworzy instancję i dodaje ją do sceny podczas montowania komponentu. Złożoność polega na tym, kiedy usunąć instancję ze sceny i kiedy ponownie ją dodać.
+
+Chociaż został zaimplementowany minimalny proces usuwania, nie jest on idealny. Oznacza to, że czasami będziesz musiał przeładować stronę, aby zobaczyć zmiany poprawnie, zwłaszcza gdy odwołujesz się do instancji za pomocą [Template Refs](https://v3.vuejs.org/guide/component-template-refs.html)
+
+```vue
+<script setup lang="ts">
+const boxRef: Ref<TresInstance | null> = ref(null);
+
+onLoop(({ _delta, elapsed }) => {
+  if (boxRef.value) {
+    boxRef.value.rotation.y += 0.01;
+    boxRef.value.rotation.z = elapsed * 0.2;
+  }
+});
+</script>
+
+<template>
+  <TresMesh ref="boxRef" :scale="1" cast-shadow>
+    <TresBoxGeometry :args="[1, 1, 1]" />
+    <TresMeshStandardMaterial color="teal" />
+  </TresMesh>
+</template>
+```
+
+Jeśli dokonasz zmiany w `color` materiału `TresMeshStandardMaterial`, zauważysz, że zmiana ta zostanie zastosowana, ale rotacja już nie będzie działać. Dzieje się tak, ponieważ instancja jest usuwana i tworzona od nowa.
+
+:::tip
+Więc, jako **regla general**, powinieneś przeładować stronę, gdy nie widzisz dokonanych zmian.
+:::
+
+Mówiąc to, pracujemy nad lepszym rozwiązaniem na to 😁. Jeśli masz jakieś pomysły, jak to rozwiązać, daj nam znać.
+
+Możesz śledzić dyskusję na [HMR Disposal Discussion](https://github.com/Tresjs/tres/issues/23)
+
+## Reaktywność
+
+Wszyscy kochamy reaktywność 💚. Jest to jedna z najpotężniejszych cech VueJS. Jednak musimy być ostrożni podczas korzystania z ThreeJS.
+
+Reaktywność Vue opiera się na [Proxy](https://developer.mozilla.org/es/docs/Web/JavaScript/Reference/Global_Objects/Proxy). Pozwala to Vue 3 śledzić automatycznie zmiany w obiektach danych i aktualizować odpowiednie elementy DOM za każdym razem, gdy dane się zmienią.
+
+Ponieważ renderujemy scenę i aktualizujemy ją w każdej klatce (60FPS), oznacza to, że aktualizujemy scenę 60 razy na sekundę. Jeśli obiekt do aktualizacji jest reaktywny, Vue spróbuje zaktualizować ten obiekt tyle razy. To nie jest dobry pomysł 😅 i będzie miało negatywny wpływ na wydajność.
+
+Oto test wydajności różnicy między użyciem obiektu Proxy a obiektem płaskim.
+
+<figure>
+  <img src="/proxy-benchmark.png" alt="Proxy vs Plain" style="width:100%">
+  <figcaption>Fig.1 - Ejecuciones por segundo Objeto Plano vs Proxy. </figcaption>
+</figure>
+
+Źródło: [Proxy vs Plain Object](https://www.measurethat.net/Benchmarks/Show/12503/0/object-vs-proxy-vs-proxy-setter)
+
+Jeśli jesteś zmuszony do użycia reaktywności, użyj [shallowRef](https://vuejs.org/api/reactivity-advanced.html#shallowref)
+
+W przeciwieństwie do `ref()`, wewnętrzna wartość shallow ref jest przechowywana i ujawniana dokładnie tak, jak jest, i nie zachodzi reaktywność w głąb. Tylko dostęp do `.value` jest reaktywny. Źródło: [VueJS Docs](https://vuejs.org/api/reactivity-advanced.html#shallowref)
+
+### Przykład
+
+❌ Niepoprawne
+
+```vue
+<script setup lang="ts">
+const position = reactive({ x: 0, y: 0, z: 0 });
+
+onLoop(({ _delta, elapsed }) => {
+  position.x = Math.sin(elapsed * 0.1) * 3;
+});
+</script>
+
+<template>
+  <TresMesh :position="position" cast-shadow>
+    <TresBoxGeometry :args="[1, 1, 1]" />
+    <TresMeshStandardMaterial color="teal" />
+  </TresMesh>
+</template>
+```
+
+✅ Poprawne
+
+```vue
+<script setup lang="ts">
+const position = { x: 0, y: 0, z: 0 };
+const boxRef: ShallowRef<TresInstance | null> = shallowRef(null);
+
+onLoop(({ _delta, elapsed }) => {
+  boxRef.value.position.x = Math.sin(elapsed * 0.1) * 3;
+});
+</script>
+
+<template>
+  <TresMesh ref="boxRef" :position="position" cast-shadow>
+    <TresBoxGeometry :args="[1, 1, 1]" />
+    <TresMeshStandardMaterial color="teal" />
+  </TresMesh>
+</template>
+```